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Preface 



This book not only provides you with the opportunity to discover all the basics of 
Play! Framework 2, but also gives you an insight into its advanced features. This 
new version of Play! Framework has inherited a lot of features from the previous 
versions, but it has also learned from them. Thus, it comes with fresh thoughts, 
a clear vision, and amazing new APIs. 

The book will focus on what kind of applications can be built using Play! 
Framework 2, and what kind of technologies can be used easily with it. In 
order to demonstrate how it can be easy and fast, we'll build a full application 
from scratch, integrating as many functionalities as will be needed by any modern 
web application. 

Given that Play! Framework 2 can be used with both Java and Scala, you'll be 
introduced to the Scala programming language. However, most of the examples 
are in Java. 

What this book covers 

Chapter 1, Getting Started with Play! Framework 2, introduces readers to Play! 
Framework 2 and helps them discover how easy it is to bootstrap your development 
environment and take a fast track to creating your first application. 

Chapter 2, Scala - Taking the First Step, covers just enough of Scala so as to enable you 
to create advanced Scala templates. 

Chapter 3, Templating Easily with Scala, keeps you in touch with the Scala 
programming language while creating server-side templates. We'll see how to 
produce views for content and how to combine them. From this chapter, we will 
start making the application that we will build along with the book. 
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Chapter 4, Handling Data on the Server Side, explains how to create data on the 
server side, how to add constraints to them, and then how to generate views on 
them, while keeping in mind that a web application, especially a CRUD one, mainly 
deals with data on both server and client sides. By the end of this chapter, you'll be 
able to create a flow between the browser and the database. 

Chapter 5, Dealing with Content, covers how easy it will be to manage different 
representations of data. We'll introduce how streams are handled by Play! 
Framework 2, using body parsers. We'll also take the opportunity to use JSON 
to share our data between the client and the server sides. Also, we'll see how to 
create an Atom feed of the same data. 

Chapter 6, Moving to Real-time Web Applications, demonstrates how to achieve more 
powerful features (required by any modern web applications) to deal with data in a 
real-time fashion, using the APIs provided with Play! Framework 2. You'll build an 
end-to-end workflow using CoffeeScript in the browser to consume events produced 
on a WebSocket by the server. 

Chapter 7, Web Services - At Your Disposal, covers the WS API that Play! Framework 
2 includes. This API will leave us consuming or producing content to a different 
application, using whatever representation of the data we're used to. To illustrate 
such a use case, we'll connect to Twitter's end points to consume tweets and show 
them in our application. 

Chapter 8, Smashing All Test Layers, gives an overview of all test layers that can be 
covered using the test features provided by Play! Framework 2. Being a full-stack 
framework, Play! Framework 2 not only includes binding with testing frameworks, 
but also mockups for the whole server. By the end of this chapter, you'll be able to 
test the server-side code and also the user interface using Selenium. The chapter is 
also the only one that is Scala- and not Java-oriented. 

Chapter 9, Code Once, Deploy Everywhere, explains how a Play! Framework application 
can be used in a continuous integration tool, and how to put it in production by 
following the continuous-deployment philosophy. You'll also be introduced to the 
Typesafe console that can help us monitor applications at runtime. 

Appendix A, Introducing Play! Framework 2, gives you a deeper insight into the 
underlying concepts on which Play! Framework is built. We'll see why it is so 
awesome and what its differences are with the first version. It's also a good place to 
start, where an overview of the features of Play! Framework 2 can be grasped at once. 
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Appendix B, Moving Forward, keeps you moving forward with all the very advanced 
features of Play! Framework 2 that we had to leave aside for a while. You'll also see 
that the Play! community is expanding very fast and that a lot of helpful plugins are 
already available. 

Appendix C, Materials, gives information about the publicly available sources 
on GitHub. 

What you need for this book 

As Play! Framework 2 is meant to be "full stack" and completely integrated, the good 
news is that there are no specific requirements for you or your environment to start 
creating new web applications. 

However, I could give you some common advice, for example, having random 
hardware is good enough, but having an SSD can be really helpful. This is because 
we'll be in the JVM world, where compilations will be needed and thus filesystem 
access can be intense. So just bring your machine and your preferred text editor 
(or IDE) and go ahead. 

Who this book is for 

The book does not focus on algorithms or model patterns at all. Instead, this 
book is for web developers. The reader must be interested with the Web world 
without (especially) being an expert in making web applications. However, a good 
understanding of third-tier applications over HTTP will be a plus. 

The skills required are as few as the prerequisite knowledge required is less. The 
reader should be familiar with object-oriented languages and have some notion of 
client-side technologies such as JavaScript, CSS, and HTML. 

Conventions 

In this book, you will find a number of styles of text that distinguish between 
different kinds of information. Here are some examples of these styles, and an 
explanation of their meaning. 

Code words in text are shown as follows: "Now that your machine is prepared, 
we can create our first project using the play command." 
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A block of code is set as follows: 

Long chatld = Long . parseLong (queryString . get ( "chat id" ) [0] ) ; 
Map<String, String [] > queryString = request (). queryString () ; 

Any command-line input or output is written as follows: 

$> cd play-jbook 
$> play 

New terms and important words are shown in bold. Words that you see on the 
screen, in menus or dialog boxes for example, appear in the text like this: "In the new 
window, click on the Environment Variables... button." 



Feedback from our readers is always welcome. Let us know what you think about 
this book— what you liked or may have disliked. Reader feedback is important for us 
to develop titles that you really get the most out of. 

To send us general feedback, simply send an e-mail to f eedback@packtpub . com, 
and mention the book title via the subject of your message. 

If there is a topic that you have expertise in and you are interested in either writing 
or contributing to a book, see our author guide on www.packtpub . com/authors. 



[ 
[ 





Tips and tricks appear like this. 



Warnings or important notes appear in a box like this. 



] 
1 



Reader feedback 



Customer support 

Now that you are the proud owner of a Packt book, we have a number of things to 
help you to get the most from your purchase. 
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Downloading the example code 

You can download the example code files for all Packt books you have purchased 
from your account at http : //www . packtpub . com. If you purchased this book 
elsewhere, you can visit http : / /www . packtpub . com/ support and register to have 
the files e-mailed directly to you. 



Errata 

Although we have taken every care to ensure the accuracy of our content, mistakes do 
happen. If you find a mistake in one of our books —maybe a mistake in the text or the 
code— we would be grateful if you would report this to us. By doing so, you can save 
other readers from frustration and help us improve subsequent versions of this book. 
If you find any errata, please report them by visiting http : / /www . packtpub . com/ 
submit-errata, selecting your book, clicking on the errata submission form link, 
and entering the details of your errata. Once your errata are verified, your submission 
will be accepted and the errata will be uploaded on our website, or added to any list 
of existing errata, under the Errata section of that title. Any existing errata can be 
viewed by selecting your title from http : / /www. packtpub . com/support. 



Piracy 

Piracy of copyright material on the Internet is an ongoing problem across all media. 
At Packt, we take the protection of our copyright and licenses very seriously. If you 
come across any illegal copies of our works, in any form, on the Internet, please 
provide us with the location address or website name immediately so that we can 
pursue a remedy. 

Please contact us at copyright@packtpub . com with a link to the suspected 
pirated material. 

We appreciate your help in protecting our authors, and our ability to bring you 
valuable content. 



Questions 

You can contact us at questions@packtpub . com if you are having a problem with 
any aspect of the book, and we will do our best to address it. 




Getting Started with 
Play! Framework 2 

This chapter will introduce Play! Framework 2 by demonstrating its basic features 
and overall structure. 

We'll cover the bootstrapping tasks, including creating projects and running them. 
To tackle this, the following list of topics will be put to use: 

• Set up Play! Framework 2 - installation and configuration 

• Create projects (Java and Scala) 

• Set up your IDE for the project 

• First contact with the build tool 

• See the projects in action 

• Review the code within default projects 

• Experiment by modifying the code 

Preparing your machine 

As the first step of using Play! Framework, we'll see how to install it on our machine 
with minimum requirements as possible. The goal is to have our basic environment 
set up in a few and simple tasks. 
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Downloading the package 



The simplest way to install Play! Framework 2 is to download it from the website 
http : //www . playf ramework . org/. This is fairly simple. Just go to the Download 
link in the upper-right-hand side of the website and click on the Latest official 
version link. This will download a . zip file to your system. Unzip it to a location 
of your choice. 

This package can seem quite large (almost 150 MB, compressed), but if we have a 
look inside, we'll see that it contains everything needed to run the framework or for 
the developer to develop with it. That's because it is composed of documentation, 
libraries with their dependencies (repository), and the framework itself. This means 
that even when disconnected, we'll have access to all the information needed. 

Let's have a look at the documentation folder: 

• manual: This folder contains the documentation that can also be found on 
the website 

• api: This folder contains the Javadoc and Scaladoc of the Play! APIs 

Apart from these, we'll find the samples folder. It is a mine of snippets for common 
tasks and is split into two parts: j ava and scala. As you can imagine, here we have 
an access to plenty of simple or advanced Play! 2 projects that have been written in 
both in Java and Scala. For example, the forms sample project that introduces some 
patterns to deal with forms, or the websocket-chat sample project that goes deeper 
into the details of using the more advanced Play! 2 features. 



At this stage, we're almost done; all we have to do is to update our path 
environment variable to point to the extracted folder, which contains the 
command-line tool: play!. 

However, before that, as Play! Framework 2 is a JVM web framework, you must 
check that Java 6 or a higher version is installed and available for use. 



Installing 




However, for "non-JVM" people, you can get the last version 
from http : / /www . oracle . com/ technetwork/ j ava/ 
j avase/downloads/ index . html. 
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Microsoft Windows 

Let's perform the following steps to update our path environment variable: 

1. Press the Windows key. 

2. Type sys var. 

3. Select Edit the system environment variables. 

4. In the new window, click on the Environment Variables... button. 

5. In the user variables panel, we can now add/edit the path variable with the 
path to the Play! installation. The following screenshot summarizes what we 
just did: 



► Control Panel ► 



System 



i 1 Edit the system environment variables 



System Properties 



Computer Name | Hardware | Advanced | System Protection | Remote | 



You must be logged on as an Administrator to make most of these changes. 



E nvi ro n merit Va ri a b I e: 
User variables for noootsab 



Ed 



Variable 


Value 


TEMP 


%USERPROFILE%vAppData\Local'rTemp 


TMP 


%USERPROFILE%\AppData'.l_ocalVrerrip 



New User Variable 

Variable name: 
Variable value: 



C:\play-2.Q. 2| 



Edit.. 



Delete 



Cancel 



ance 

iffects. processor scheduling, memory usage, and virtual memory 



ofiles 

p settings related to your logon 



Settings.. 



Settings.. 



and Recovery 

startup, system failure, and debugging information 



Settings.. 



Environment Variables.. 



Apply 
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Mac OS X 

Open a terminal using the word terminal in Spotlight. Then type the 
following commands: 

$> cd - 

$> echo 'export PATH=$PATH : <PATH-TO-Play> 1 >> . bashprof ile 



Ubuntu 

Open a terminal using Ctrl + Alt + T. Then type the following commands: 
$> cd - 

$> echo 'export PATH=$PATH : <PATH-TO-Play> ' >> .profile 



The Typesafe Stack 

As you may know, Play! Framework is now part of a more general stack provided by 
Typesafe, which redefines almost all the layers of the modern applications built on 
top of the JVM: the Typesafe Stack 2. 

Roughly, it begins with the language (Scala), continues with a concurrent layer 
(Akka), and completes with a web layer (Play!). 

It's quite helpful to install the stack rather than Play! 2 alone because it will install 
versions that are validated to work together. 

Checking if it's okay in your terminal 

At this stage, we can use the command-line tool embedded with Play! Framework 2. 
This tool, simply named play!, is the very beginning as it will start the whole 
machinery. For that, let's open a terminal depending on our OS, as follows: 

• Microsoft Windows: Press the Windows key + R. Then type cmd and 
press Enter 

• Mac OS X: Open Spotlight. Then type terminal and press Enter 

• Ubuntu Linux: Press Ctrl + Alt + T 
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We're ready to check whether our Play! environment has been correctly set up. 
Let's enter the following command: 

$> play 

Once done, you should see the following screenshot: 



noootsab@noootsab-xps -ubuntu : $ play 
Getting net. java.dev. jna jna 3.2.3 ... 
:: retrieving :: org.scala-sbt#boot-app 
confs: [default] 

1 artifacts copied, 9 already retrieved (838kB/9ms) 
Getting Scala 2.9.1 (for console)... 
:: retrieving :: org.scala-sbt#boot-scala 

confs: [default] 

4 artifacts copied, 9 already retrieved (19939kB/23ms) 
Getting play console 2.9.1 2.9.2 ... 

:: retrieving :: org.scala-sbt#boot-app 
confs: [default] 

5 artifacts copied, 9 already retrieved (3667kB/9ms) 



I '_ \l 1/ _' I II LI 

I _/U\ l\_ (_) 

LI l_/ 

play! 2.9.2, http://www.playfraneiiprk.org 

This is not a play application! 

Use "play new" to create a new Play application in the current directory, 

or go to an existing application and launch the development console using "play". 

You can also browse the complete documentation at http://www.playframework.org, 

noootsabgnoootsab-xps- ubuntu :~$ \_ 



This means that Play! is correctly installed. Bravo! Don't worry about the message; 
it only tells you that you weren't in a valid Play! project folder, that's all! 

What's interesting at this point is that the play! tool is actually starting an SBT 
console (http : / /www . scala-sbt . org/ release/docs/ index . html). 
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You can also get some help from the tool by executing: 
$> play help 



noootsabgnoootsab-xps-ubuntu * $ play help 

~~\\ r!_l 
i\_ o 

play! 2.0.2, http: //www . playf ramework . org 

Welcome to Play 2,0] 

These commands are available: 

license Display licensing Informations. 

new [directory] Create a new Play application In the specified directory. 
You can also browse the complete documentation at http://www.playframework.org. 



As you may notice, it recommends that you create your first application. Here we go! 

Creating your first project 

Now that your machine is prepared, we can create our first project using the 
play command. 

As we have just seen, Play! Framework 2 comes with a handy command-line tool, 
which is the easiest and fastest way to create a new project. The following screenshot 
shows how to create a project with Java stubs: 



noootsab@noootsab-xps-ubuntu:~/src/book$ play new play-jbook 

l/~'~flflJ 
_/U\ l\_ (_) 

LI l_/ 

play! 2.0.2, http://www.playfranework.org 

The new application will be created in /home/noootsab/src/book/play- jbook 

What is the application nane? 
play jbook 

Which template do you want to use for this new application? 

1 - Create a simple Scala application 

2 - Create a simple Java application 

3 - Create an empty project 

> z 

OK, application play-jbook is created. 
Have fun! 
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Downloading the example code 

You can download the example code files for all the Packt books you 
have purchased from your account at http : / /www . packtpub . com. 
If you have purchased this book elsewhere, you can visit 
http : / /www . packtpub . com/ support and register to have 
the files e-mailed directly to you. 



As we can see from the previous screenshot of the console, in order to create a 
brand new application in a directory, we just have to use the play! command-line 
tool with a parameter (named new) followed by the name of the new application 
(play- j book). 

The tool will ask us to specify whether our application is a Scala or Java application, 
or even an empty project. In the first two cases, the structure of the application will 
be created along with the source files for the chosen language. In the third case, only 
the structure will be created— without sample code though. 

By the way, the last option has been removed in the Play! 2.1 I 
^C^"- * release. Thus only the first two options remain now. I 

Let's have a very quick overview of the created structure (we'll go into further details 
later on in this book). 

At first, a new directory will be created with the name of the application, that is, 
play- j book. This will be the root of our project, so the whole structure is inside this 
directory and looks like the following screenshot: 



• Home dev play-jbook 




Search 
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app 


conf 


projec 
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This 
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README 
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Let's describe each folder briefly: 

• app: This is the root of all the server-side source files, whatever type they are 
(Java, Scala, server-side templates, compiled scripts, and so on). At creation, 
only two subfolders will be created: controllers and views. 

• conf : This folder is dedicated to all of the files meant to configure the 
application itself, external services, or whatever the application could 
need at runtime. 

• pro j ect: As SBT is used behind the curtains, the pro j ect folder is meant to 
contain all of the necessary files to configure this tool. 

• public: This last folder will simply contain all of the external files that can 
be accessed by the clients, such as stylesheets, images, and JavaScript source 
files. A dedicated folder has been created for each type as well. 

• test: This last folder will contain all all test files with some examples provided. 

Keeping your habits 

In the previous section, we installed the framework on our machine, and we even 
created our first application. The next natural step for any developer would be to 
open the project in our preferred IDE. 

It is good for us that Play! has already configured everything in order to generate the 
project and module files required by the most popular IDEs. 

Let's see how to configure Eclipse and IntelliJ IDEA, and then we'll see how to deal 
with another editor: Sublime Text 2. But first of all, you will have to enter your 
application in the terminal: 

$> cd play-jbook 
$> play 



noootsab@noootsab-xps-ubuntu:~/src/boQk$ cd play-jbook/ 
noootsab@noootsab-xps-ubuntu:~/src/bQok/play- jbookS play 
[Info] Loading global plugins from /hone/noootsab/ .sbt/plugins 

[Info] Loading project definition from /home/noootsab/src/book/play- jbook/project 

[info] Set current project to play-jbook (in build ftler/home/noootsab/src/book/play- jbook/) 



I '_ \[ ]/_'[] 1 LI 
j l\_ (_) 

play! 2.9.2, http: //www. play franework.org 

> Type "help play" or "license" for more information, 

> Type "exit" or use Ctrl+D to leave this console. 



[play-jbook] $ [] 
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While executing, you might see checks for a lot of things (dependencies), but nothing 
is failing and nothing has been downloaded (if you're disconnected). That's because 
everything has already been packaged in the Play! 2 . zip file — especially all of the 
dependency JARs are provided in Play! 2's dedicated repository. 

Being in the console, you now have access to plenty of commands related to your 
project (this should sound like deja vu for those who've used Maven plugins); for 
example, version, name, and dependencies. Just try them, or hit the Tab key twice. 

Commands have been created to execute tasks such as generating files based on the 
project. Among them is the generation of the IDE settings. 



Using Eclipse 

Eclipse is probably the most commonly used editor by the Java community, the 
advantages being: it's free, has a strong community, and provides a powerful 
extension framework. 

That's why this section will have two sections: one for the classical Eclipse Juno and 
one for the Scala version named Scala IDE (http : //scala-ide . org/). 



Eclipse Juno 

While in the play! console, you can ask it to generate the Eclipse project configuration 
by simply invoking the eclipse: 



[play jbook] S eclipse 

[Info] About to create Eclipse project files for your project(s). 
[info] Successfully created Eclipse project files for project(s): 
[info] play-jbook 

noootsab@noootsab-xps-ubuntu:~/src/book/play-jbook$ Is -a 

app .classpath conf .gitignore project .project public README .settings target test 



This will generate all the specific files necessary to configure an Eclipse project. 
Now we can open Eclipse and import the project into it. For that, let's perform the 
following steps: 

1. Go to File | Import. 
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2. Then select General | Existing Projects into Workspace and click 
on Next: 



Q Import 


Select 

Create new projects from an archive file or directory. 






Select an import source: 






[type filter text 




<a] 




T & General 
§i Archive File 






\S Existing Projects into Workspace 






Q, File System 

CL Preferences 
T &CVS 

SI Projects from CVS 
* G=> Install 

► & Plug-in Development 

► & Run/Debug 
















(f) <Back | Next> , 


Cancel 


Finish 
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3. A new panel invites you to browse your filesystem in order to locate the 
project folder. So select it, click on OK, and then on the Finish button: 



Import Projects 

Select a directory to search for existing Eclipse projects. 



® Select root directory: |/home/noootsab/src/book/play-jbook 

Select archive file: 
Projects: 



play-jbook (/home/noootsab/src/book/play-jbook) 



Q Copy projects into workspace 
Working sets 
□ Add project to working sets 

Working sets: | 



Browse... 



Browse... 



Select All 



Deselect All 



Refresh 



Select... 




The following screenshot is what you should see now: 
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public class Application extends Controller { 






T © Application 
© s index() : Result 
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public static Result index!) { 








► views 








return oft (index. renderf "Your new application is ready."]); 

} 
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Looking at the screenshot, we should notice the following points: 

• Some folders have been marked as sources and test files (app and test) 

• A bunch of libraries have been mounted on the project (including the 
Play! library) 

• The Play! API is recognized along with the generated template sources 
(index . render) 

Using Scala IDE 

For projects that involve the Scala source code, even though a Play! project can contain 
both Scala and Java source code, the Scala IDE is probably the best choice. The Scala 
IDE is actually a customized Eclipse version, which has Scala as the main focus. To set 
up a Scala project in the Scala IDE, we'll first need to create the project using the play! 
console in a similar way to how the Java version was created. This is shown as follows: 



noootsab{jjnoootsab-xps-ubuntu:~/sf-c/book$ play new play-shook 

f I _f I 

I '_ \l 1/ _' I II LI 

I _/U\ l\_ (_) 

LI l_/ 

play! 2,9.2, http://www. playfranework.org 

The new application will be created in /home/noootsab/src/book/play-sbook 

What is the application name? 
play-sbook 

Which template do you want to use for this new application? 

1 - Create a simple Scala application 

2 - Create a simple Java application 

3 - Create an empty project 

> 1 

OK, application play-sbook is created. 



Have fun! 
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The very next step is to install the Scala IDE. As it's an Eclipse plugin, all we have to 
do is to start an Indigo version of Eclipse. Then go to Help | Install New Software... 

In the Work with field, we'll enter the path from which the Scala IDE team is 
distributing their plugin (http : //scala- ide . org/download/current .html). 

In order to import our project, we can just repeat the same steps that we performed 
earlier in the Eclipse Juno section. At the end, we will have the following screenshot: 



e ft 



I Package Explorer H 

* .J play ibood 
* k9ipp 
* EH controllers 



hi* test 
" m.?v.jlj Lib r j ty [2.5,2] 
r lit Referenced Libraries 

* — pLay_2.9. 1 jar /ho me/no oot 
*■ templatn_J.9J.|ir'/home/. 



Application.Mata £3 

package controllers 

L inpflrl play. dpi. 

object Appl iear iait extendi Controller ■' 

de-f index ■ Action ■ 
OklYinre.htnl . indent 'Vour new application ii ready, 'H 



£ Outline H 



E A *t V • V 



' import declarations 
© AppUtdLion 
* Index: pLiy.tpl.mvtd 



As expected, the features brought by Eclipse for the Java version still remain in 
this version. So do the features including syntax coloring for the Scala code, code 
browsing, contextual documentation, and so on. 



IntelliJ IDEA 

IDEA is a great and well-known IDE despite the fact that it isn't open source or 
totally free. At least, we can choose between the free version (Community) —which 
has less features — and the other one (Ultimate). 



[ 



At the time of writing this book, a Play! 2 plugin is on its way for the 
paid version, however we will try to stick with the free only IDE. But 
for those interested in this plugin, check the link at http : / /plugins . 
j etbrains . com/plugin/ index?pr=&pluginld=7080. 
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Let's go back to the play! console. We can now invoke a new task called idea: 



noootsab@noootsab-xps-uburitu:-/s rc/ book/ play- j books pLay 
[Info] Loading global plugins from /home/noootsab/.sbt/plugins 

[info] Loading project definition from /hone/noootsab/src/book/play- jbook/project 

[info] Set current project to play-jbook (in build file:/home/noootsab/src/book/play- jbook/) 



I '_ \l 1/ _' I I I LI 

I _/[_[\ l\_ (_) 

U \—l 

play I http: //www. play franework.org 

> Type "help play" or "license" for more information. 

> Type "exit" or use Ctrl+D to leave this console. 

[play-jbook] S idea * 
[info] Trying to create an Idea module play-jbook 
[info] Excluding folder target 

[info] Created / hone/ nooo t sab/ src/ book/ play-jbook/ . idea/IdeaPro ject .in I 
[info] Created / hone/ nooo t sab/ src/ book/ play-jbook/ .idea 

[info] Excluding folder /home/noootsab/src/book/play- jbook/ target/ scala-2.9.1/cache 

[info] Excluding folder /home/noootsab/src/book/play- jbook/ targe t/scala- 2. 9.1/ classes 

[info] Excluding folder /home/noootsab/src/book/play- jbook/ targe t/scala- 2.9.1/ classes_managed 

[info] Excluding folder /home/noootsab/src/book/play- jbook/ target/ streams 

[info] Created /hone/noootsab/s rc/book/ play- jbook/ .idea_modules/ play- jbook. inl 

[info] Created /home/noootsab/src/book/play- jbook/ .idea_modules/ play- jbook- build. tnl 

[play-jbook] $ Q 



This will create a fully configured project with the related modules for our project. 

Now we can simply open the folder itself as a project in IDEA. For that, we need to 
go to File | Open Project and navigate to the project folder: 
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The following screenshot shows what we should get after having confirmed our project 
folder. Hopefully, we will get the same kind of features that we get with Eclipse. 



File Edit View Navigate Code Analyze Refactor Build Run Tools VCS Window Help 
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'C) Application.java 



package controllers; 
□ import . . . 

public class Application extends Controller { 

f) public static Result index () { 

return oMindex , renoer("Your new application is ready.")); 

} 

I 



[ 



A free Scala plugin exists, bringing a lot of features and 
enabling us to use IDEA for our Scala projects too. 



] 



Sublime Text 2 

As Play! is fully integrated, we can sometimes feel an IDE to be overkill because of 
two things: 

• IDEs support of Play! is very young (obviously) and limited 

• Play! is so easy that for most of the time we only need the documentation and 
the Javadoc (or Scaladoc) of the provided API 

Having said, that an IDE is helpful for code completion/ navigation and maybe 
sometimes in debugging sessions, but I think their need decreases slightly when 
used with a simple framework like Play!. 

Sublime Text 2 comes with features than an IDE. Actually, it comes with pure editing 
features, such as multiple selects for batch edition, quick find, embedded console, and 
macros. Moreover it takes fewer resources (thankfully, when we develop without 
any power slots available). Another feature is that it has the best support of the Scala 
template used by Play! 2 including syntax coloration, snippets, and more. 
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To install it, we can download the installer related to our operating system from 
http : //www . sublimetext . com/2 and execute it. Now that Sublime Text 2 is 
installed, we can also enable two packages: 

• The package manager can add and search a package repository directly from 
the Sublime Text 2 console. See http : / /wbond.net/sublime_packages/ 
package_control for more details. 

• The Play! 2 support package installation is very easy and is well 
explained at https : / /github . com/guillaumebort/play2 - 
subl ime t ext 2 #installat ion- instruct ions. 

Now with everything set up and a Sublime Text 2 window opened, what we could 
do is simply add our project folder to it using the console. So press Ctrl + Shift + P 
and type Add Folder, and then browse to our project. The following screenshot is 
what we should have: 



OPEN FILES 








FOLDERS 










package controllers; 




T play-jbook 


2 




▼ app 
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import play,*; 
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import play , mvc . *; 




T controllers 
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import views.html.*; 




Application.java 


6 




► views 


8 


public class Application extends Controller { 




► conf 


9 
10 


public static Result index! ! { 




► project 


11 


return ok( index , render! "Your nev application is ready,' 


)); 


► public 


12 
13 


} 










14 


} 





Now, we can very often save a few lines of code by simply using the snippets 
that are available for all components of a Play! 2 application (code, configuration, 
templates, and so on). Let me introduce some of the most useful ones: 

• pf oreach: This creates a loop over sequence in a template 

• bindf orm: This binds data from a form using the request content 

• ok/ redirect: They create the related HTTP result 

• sessionget/ session set: They retrieve or set a value to the session 

Check the following page for an exhaustive list: 

https : //github . com/guillaumebort/play2 - sublimetext 2 #code- snippets 
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Simple Build Tool 

In the earlier sections, we used the play! console a lot to access the tasks related to 
our project. Actually, this command-line tool is a customization of Simple Build 
Tool (SBT). 

SBT is a powerful and easily extensible build tool like Maven or Ant. But, where the 
latter rely exclusively on the external DSLs to manage their configuration, SBT uses 
an internal Scala DSL for that. Of course, this isn't its only advantage. 

What is interesting at this point is that SBT doesn't need any specific integration with 
IDEs because it's simply Scala code. As one isn't required to know Scala in order to 
create or update an SBT configuration, let's cover how to deal with its common tasks. 

Looking into the pro j ect folder, we'll find a Build . scala file, which contains the 
basic configuration of our build. It briefly defines play . Pro j ect: an extension of a 
regular SBT Pro j ect. The following screenshot shows what it contains: 

\~j Build. scala 



1 impo rt sbt . _ 

2 import Keys._ 

3 import play . Pro] ect ._ 
4 

5 object ApplicationBuild extends Build { 

6 

val appName = "play- j^book" 

val appVersion - "1 . Q- SNAPSHOT" 

9 

val appDependencies = Seq( 
11 // Add your project dependencies here, 

j avaCore, 
j avaJdbc, 
j avaEbean 

15 ) 
16 

val main = pi ay . Pro j ect ( appName , appVersion, appDependencies ). sett ings ( 

18 // Add your own project settings here 

19 ) 

2G 

21 } 
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Adding a third-party dependency 

Even if Play! 2 already integrates a lot of libraries that are usually sufficient, it often 
happens that we need to add new dependencies to our projects to access new features 
(such as a statistics library) or provided one with a different vision (such as a new 
logging library). 

As an example, we'll add the latest version of Guava (http : //code . google . com/p/ 
guava-libraries/) to our project. 

As Scala is powerful enough to create DSLs, SBT took the opportunity to provide a 
DSL to define La project. Let's see an example of adding a dependency using this DSL. 

For that, the Build, scala file already defines a sequence (appDependencies) that 
can be seen as an immutable j ava .util . List in Scala. This sequence is meant to 
contain all the extra dependencies that we'll need to be added to our project. 

As SBT can use the Maven or Ivy repositories, and is configured to check the 
common public ones, what we'll do is add Guava using its Maven group id, 
artif actld, and the required version. 

Let's see the syntax: 

tial appDependencies = Seq[ 
j avaCo re , 
j avaJdbc , 
j avaEbean , 

//groupld > artifactld > version 

"com .google . guava" * "guava" \ "12.Q.1" 

) 



Later on, this sequence will be used in the play . Pro j ect configuration as a parameter. 

Repositories 

In the previous section, we saw how to add new dependencies to our projects; but 
this method will only work for the libraries that have been deployed on public 
repositories. However, as developers, we'll face two other cases: 

• Locally built libraries (either open source or owned) that are placed in our 
local repository 

• A library that is not available in the common public repositories 



Chapter 1 



The way to go for such cases is to tell the play . Proj ect configuration to look into 
the other repositories that we have configured, shown as follows: 

val 1 ocaT MavenRepo = "Local Haven Re posit ory " at f il el Pat h . use rHome . absol Lite Pat h+ " / . B^VegjDsxtCM^ " ) . t oURI . to URL . to St ring 
val noootsabSnapshots = "Noootjjb SNAPSHOTS" at "htt^s^J^^ Cv// <\«/> w w/ ^ vA*w^ , " ;r ^'^iw*w ■j^-^^SizSB^S/" 

val main = play . Proj ect ( appName, appVersiorij appDependencies) . settings! 
// Add Repos to the cornmon ones 

resolve rs + += Seq (I ocal MavenRepo, nooot sabSnapshot s J 



A DSL is meant to be code-readable by expressing and using business-specific concepts 
for a specific field. Let's check if it is, by reviewing the repositories' declaration. 

A repository is nothing more than a folder that is accessible using a path, and 
which has a structure that follows some convention. So, a declaration is composed 
of three things: 

• A name (Local Maven Repository) 

• A protocol or an access method (file is a function that takes a path and 
declares it as a filesystem resource) 

• A path: the location of the repository 

For convenience, we store these definitions in val (which are immutable variables) 
in order to use them in the play . Proj ect declaration. This declaration is done by 
adding the existing resolvers (or repositories) to our new sequence of repositories 
(or resolvers) using the ++= operator. 

It's alive and not empty! 

In the earlier sections we saw how to create a project, import it into our development 
environment, and we even learned how to attach new libraries to it. 

Now it's time to look at what has been created so far. As we've chosen not to create 
an empty project (which was the third option proposed by the play new command), 
we already have a certain amount of things available for our perusal. 

Rather than looking at the files, we are going to run the application using a play 
command to compile everything and start a server that will run our application. 
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To do this, enter the play! console and type run: 



ay-jbook] $ run 



— (Running the application from SBT, auto- reloading Is enabled) 
[Info] play - Listening for HTTP on port 9000,., 

(Server started, use Ctrl+D to stop and go back to the console..-) 



As we can see, the console tells us that it has started the application and an HTTP 
server is available on port 9000. 

The next logical step is to open our browser and request this brand new server by 
going to the URL http : //localhost : 9000/. 

Once done, our page should look like the following screenshot: 



+■ •* O H O localhosts 



Your new application is ready. 




Unable to connect to the Internet 

Chromium can't display the webpage becajse your computer isn't connected to the Int 



Welcome to Play 2.0 



Congratulations, you've just created, a new Play application. This page will help you in the few next 



Your are using Play 2.0.2 



Why do you see this page? 



The conf /routes file defines a route that tells Play to invoke the Application .index action 
whenever a browser requests the 1 URI using the GET method: 



# Home page 

GET / 



controllers .Application . index ( ) 



So Play has invoked the cont rollers .Application . index method: 



public static Result index( ) = { 
return o1c(index.render("Your new application is ready.")); 



^ chromium 



Local doc timsn; Alien 
Browse the Java API 

Start here 

Using the Play c :]■?■: 
Seaing up your preferred IDE 
| Your flrs^application 



Chapter 1 



What is being shown is the default welcome web page that Play! 2 has made 
available for us. 

As shown in the previous screenshot, this page already contains a lot of information, 
essentially the basics (that we'll cover next) and some help about the environment 
(which we've just covered). 

Recall that when we installed Play!, the Play! Framework 2 installation directory 
contained a documentation folder. Now that we have an application running, 
we'll see that this documentation wasn't there for no reason. 

If we pay more attention to the welcome page, there is a Browse menu on the right 
side of the page. This menu has two items. Let's have a quick overview of them now. 

The first item, Local documentation, is a reference to the manual folder of our 
installation. So we can access the current Play! version's documentation directly 
from our application (at development time only, not in production). 

The second item is the API and is discussed in the next section. 



Browsing the Java API 

Before entering into any details, we must have noted that the menu has the word 
Java in its name. That's because Play! has detected (we'll see how later) that we're 
running a Java application. 

On entering this menu, we'll see the following web page: 
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As expected, we obtained the well-known Javadoc website. We won't cover the API 
here, but the good thing to note is that we'll always have direct access to it without 
having to generate it, browse the Web to find it, and so on. 

[rlTX This kind of website is also available for the Scala version, 
but it has a slightly different presentation. 

Understanding the core pieces 

In this section, we'll have a good time looking into the files that have been generated 
while creating our project. 

First of all, we should wonder what is responsible for taking a URL and deciding 
what is to be done with it. That's done through routing. 

Routing 

As discussed earlier, we went to the root path of our running application 
(http : //localhost : 9000/). What we got was an HTML page containing 
information and links to some documentation — the welcome page. 

What happened is that the browser took a URL and sent a get request targeting 
the / path of our server. 

At this stage, Play! Framework 2 enters the game; it will try to find an action 
somehow related to the received request using two pieces of information: 
a method (get) and a path (/). 

For that, Play! uses a kind of mapping file, routes, that can be found under the conf 
folder. Let's see what it looks like so far: 



OPEN FILES 








# Routes 

# This file defines all application routes (Higher priority routes first) 
# 

# Home page 

GET / cent rollers , Application , index ( ) 


FOLDERS 
T book_chapters 
V eh a pi 
T play-jbook 


1 

2 
3 
4 


► app 
Y conf 

app 1 i rati l 


8 
9 
10 


# Map static resources from the /'public folder to the /assets URL path 

GET /assets/*! ile cont rollers , Assets , at ( path="/public" , file) 








► project 
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As we can see, the comments begin with the hash character (#), and the 
relevant information is in the lines with three columns, as we can see in 
the following screenshot: 

GET / cont rollers . Application , index[ ) 



Indeed, each row defines how to access server-side functionalities using HTTP, 
and is composed of three columns: 

• get: This is the first column that contains the method used in the request 

• /: This second column contains a relative path (to the application context, 
which is void in our case) 

• controllers .Application, index ( ) : This third column is reserved for the 
action to be invoked 

So, when the Play! application is asked for a route, it looks in its defined mapping 
to find the perfect match using the method (get) and the path (/). In this case, it will 
stop at the first line. 

Having found a definition, Play! will call the action (third column): controllers . 
Application, index ( ) , which calls the index method in the Application class 
that resides in the controllers package. We'll cover the action part in detail in 
the next section. 

Now let's have a look at the second line of the routes file: 



# Map static resources from the /public folder to the /assets URL path 

GET /assets/*f ile cont rollers . Assets . at ( pat h=" /public" , file) 



What it does is map all of the get requests on the paths that start with /assets/. And 
the next portion, *f ile, stands for: all next characters (*) must be kept in a resulting 
string that will be named file. This variable is very important because it can be used 
in the action part of the mapping to initialize data. Let's read ahead for more. 

An example of matching requests would be the one that asks for the jQuery asset 
(the version 1.7.1 is available by default): http : //localhost : 9000/assets/ 
j avascripts/ j query- 1.7. 1-min . j s 

Looking at the mapping, it says that the file variable will hold the j avascripts/ 
j query- 1 .7.1. min . j s string. Let's see how this value can be used in the action. 
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In the second line, the action is the at method in the controllers .Assets class; its 
signature has two parameters: 

• path: This is the source folder that will be the root 

• file: This is the path to the wanted file, which is relative to the previously 
defined root folder 

To check which file will be retrieved, let's have a look at the source under public/ 
j avascripts and verify that the j query- 1 .7.1. min . j s file is present. 

OPEN FILES 



jquery-1.7.1.min.js 



FOLDERS 
V play-jbook 

► .settings 

► app 

► conf 

► logs 

► project 
▼ public 

images 
T javascripts 



jquery-1.7.1.min.js 



! stylesheets 



We'll see in the later chapters how we can define a more advanced matching system 
that involves type checking, conditional data extraction, using HTTP methods other 
than get, defining HTTP query parameters, and so on. 

Action 

An action in Play! Framework 2 is the business logic that defines an HTTP request. 
It's a simple method that has a defined route declaring it as the code to be executed 
when a matching request arrives. 

The action methods are declared in a container (a class in Java) that extends the 
Controller type (either in Java or Scala). Such a container is itself usually called 
a controller. Roughly, a controller is a bunch of methods that respond to the 
HTTP requests. 



Controllers are, by convention at least, defined in the controllers package under 
the source root— the app folder. 
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If we look back at the first route, its action was controllers .Application, 
index ( ) ; it leads us to have a look at the code now. 

What I'll propose is to review the next listing in both lava and Scala, 
because they are really simple and can be an intuitive introduction 
to the Scala syntax. However, in the rest of the book, the code will be 
mostly presented in Java and sometimes in Scala. In all cases, we can 
find both versions in the code files of the book. 

We'll start by looking at the Java version: 







Application. java X 


1 


package controllers: 


2 




3 


import play.*; 


4 


import play . mvc . *; 


5 




6 


import views . html , *; 


7 




8 


public class Application extends Controller { 


9 




1G 


public static Result index!) { 


11 


return ok( index . render( "Your new application is ready.")); 


12 


} 


13 




14 


1 




Now lets take a look at the Scala version. We can see that at this stage, both are 
looking pretty much the same. 




Application. scala 



1 
2 
3 
4 
5 
6 
7 
8 
9 
1G 
11 
12 



package controllers 



import play,api._ 
import pi ay , api . mvc. 



object Application extends Controller { 

def index = Action { 

Ok ( views , html . index ( "Your new application is ready,")) 

} 



Having seen both versions, it'll be interesting to point out where they differ. But first, 
let's see what's common between them. 
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Similarities between the Java and Scala action code 

A controller is a type that extends a Controller structure provided in the 
play . api . mvc package. Now it would seem obvious that the MVC pattern 
is implemented by Play! 2, and we're just looking at the C part. 

After this, we notice that a method, index, is defined. It means something similar in 
both languages and could be phrased as follows: inform the client that the response 
is OK with an HTML content rendered from something in the views package named 
index and using a string parameter. 

The sentence is enough representative information to figure what an action is in 
Play! 2, but some keywords may require a bit more explanation: 

• Response: An action is something that always returns an HTTP response, 
which is represented in Play! 2 by the Result type. 

• Ok: The Result type must be a valid HTTP response, so it must include a 
valid HTTP status code. Hence ok is setting it to 200. 

• Rendered something: This seemingly esoteric portion of the phrase is only 
referencing what is called a template file in Play! Framework 2. In other 
words, this is about the V part of the MVC pattern. 

• String parameter: A template can take parameters to adapt itself to 
predictable situations. Here we may feel that these template parameters are 
just like method parameters; perhaps because they are. 

Differences between the Java and Scala action 
code 

Now that we've tackled the similarities, what about the differences? The very first 
noticeable distinction is the following one: 

• In Java, a controller is a class 

• In Scala, a controller is an object 

To illustrate this difference, we must know that an object in Scala can be thought 
of as a classical singleton. And actually, our Java class is a bit special due to this 
next distinction: 

• In Java, an action is a static method 

• In Scala, an action is a function 
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Strictly, a controller in Java is nothing more than a bunch of static methods, and is a 
convenient way to force a totally stateless code, which offers common functionalities. 
We're approaching the notion of a singleton without static reference to an instance 
(non-static getinstance method), because the singleton instance will be created and 
held by the Play! 2 internals. 

The Scala action definition is simply defining a new function— an object's method. If 
we omit the pure syntactical differences (the return type and keyword are missing in 
Scala), the last interesting difference is that Scala uses an additional structure: Action. 

Such Action can be thought of as a block of code executor within an HTTP context that 
could be synchronous or even asynchronous (this will be covered in Chapter 7, Web 
Services - At Your Disposal. 



So far we have learned how to map a request to some server-side code, and how to 
define such server-side code as an action in a controller. In this section, we'll learn 
what a view looks like in Play! Framework 2. 

Actually, starting from version 2, templates (or views) are Scala based (whereas in 
version 1 they were based on Groovy). That is to say, a template file is HTML mixed 
with Scala code that can manipulate the server-side data. 

As an introduction for those unfamiliar with what we covered earlier, we'll step into 
the template we saw in the Action section: views . html . index. This file is located 
under the app/views/ folder, and is named index . scala . html. 

Here again we'll see that Play! is perfectly well integrated with Java or Scala, 
showing that the templates are exactly the same in both versions. The following 
screenshot shows what it looks like in Java: 



Templates 



r 



index.5cala.html 




1 

2 
3 
4 
5 
6 



@(message: String) 



@main( "Welcome "to Play 2.Q") { 



@pl ay 20. welcome ( message, style=" Java" ) 



_ 
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Next, we can check what the Scala version has defined: 



index, scala. html X 




1 @[ message : String) 

2 

@main( "Welcome to Play 2,Q") { 

4 

@pl ay 20. welcome! message) 

6 

' } 



OK, they are not exactly the same (at first glance), but that's where it becomes really 
interesting. First of all, where is the HTML? We've just learned that a Scala template 
is a mixture (Scala and HTML), while what we have here seems to be something like 
Scala prefixed by @ ("magic character"). Actually, it's true, the magic character tells 
the compiler that a Scala instruction is about to be defined in the very next block. 

So, before talking about the difference (type = " Java " ), we'll have a quick review 
of the rest. The template starts with a parameter between the parentheses (...) and is 
prefixed with an ® character. This parameter is defining the signature of the template. 
Then we have a new expression composed of two parts: 

• The first part is invoking a certain function named main with one 
string argument 

• The second part is a curly brace block ({...}) containing another block of code 

In fact, these two parts together compose the invocation of the main function, which 
are Scala features: 

• A function can have several blocks of parameters 

• A block of parameters can be defined using either parenthesis or curly braces 

The last portion to be reviewed is the content of the last parameter block. Since it 
starts with an m character, we know that it will be Scala code. 
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Confused? Actually, in a Scala template, a curly brace is opening a staged box in 
which we can define a new output. In our case, the output is an HTML page. But the 
default index page will delegate its content generation to another function named 
welcome, located in a self-descriptive play2 object (provided by the framework). As 
Scala code is not HTML, we must use the magic character. The content rendered by 
the welcome function is what we saw while testing http : //localhost : 9000/ — an 
HTML page with documentation. But, what the heck are these functions! Still no 
HTML? Strictly speaking, a Scala template is compiled into a function, that's all. 
Keeping this in mind, we'd better look at a file named main . scala . html that should 
be located in the same folder as index . scala . html, since no import has been used at 
all. Indeed, there is (HTML) and it is shown as follows: 



main. scala.htnni X 




1 @( title: St ring) ( content : Html) 

2 

3 <!DOCTYP£ html> 
4 

5 -=:htinl = 



-=:head> 

-=rtitle>@t itl e-=:/title> 

<link rel = "stylesheet " media="screen" href="@rcutes . Assets . at ( " 

st yl esheet s/main . ess" ) "> 
"link rel = " short cut icon" type="image/png" nref="@rcutes . Assets . 

at( "images/favicon.png") "> 

vVvvV vvvvV VV^^^ 

10 <scrj.pt s rc="@ routes . Assets . at ( "n a vase ripts/n query -1 ,7.1. mm. is" 

) " t ype="t ext /] avascript " ></scnpt> 

11 </head> 

12 -=:body=- 

@content 
14 </body> 



15 </ht»l> 



As we can see, this new template contains things such as parameters, magic 
characters, and so on. If we keep aside the link and script tags, we have an 
excerpt of HTML with an almost empty body. 

Back to the parameters; we can see two blocks (similar to what we saw in the index . 
scala . html template), where the first block is declaring a title and the second one 
content. They are used to set the HTML title and the body content respectively. 




The type of content is Html, which is the Scala structure that 
can be written as HTML when invoked by the template. Thus, 
©content is a parameter that represents valid HTML to be 
written in the body of the document. 

Both the Java and Scala versions of main . scala . html are 
exactly the same. 
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This leads us to remind ourselves of the difference we saw between the index 
templates. The Java version is calling the welcome template with an extra parameter 
(given by name— another Scala feature) telling the template that the current project is 
a Java one. 

This style parameter will be used by the welcome template to show specific links 
to documentation, depending on the language. For instance, we can recall that 
earlier we got a direct link to the Java API documentation. The Scala version is not 
initializing this argument because its default value is Scala. 



Practicing 

Modifying the code and experimenting with the tool is probably the most fun part 
for developers like us. In the next sections, we'll try to adopt what we have learned 
so far to see what kind of results we can get very easily. 

Let's start with the view part. 



Modifying the template 

We'll first try to slightly modify the index . scala . html template in order to replace 
the default welcome page with a bunch of self -coded HTML. 

To keep it very simple, that is, without modifying anything else other than the index 
template itself, we'll try to disPlay! the given message in a header. For that, the first 
thing to do is to remove the call to welcome: 



index.scala.html x 




1 @( message: String) 

2 

@main( "Welcome to Play 2.0") { 

4 
5 

G } 



That was very simple. Now, to render some HTML, we'll have to fill in an Html value 
in the second parameter —the curly braces block: 





index. scala. html t \ 






^(message: String) 




2 






3 


@main( "Welcome to Play 2,0 


) { 


4 






5 


<hl>@m e s s a g e </ hl> 




6 








} 
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We've just written the most common HTML body ever, but also asked Play! to 
echo the content of the message variable. This message variable came from the 
controller with the Your new application is ready, value. If we check 
http : //localhost : 9000 again, the following screenshot is what we should get: 



/ P> Welcome to Play 2.0 
<- O ft lO localhost:9000 



Your new application is ready. 



Not pretty, but at least we've made it ourselves. However, did you notice one thing? 
We don't have to package the template to compile it, or whatever a "classic" Java web 
application would require. What we have to do is simply save the file and check in 
the browser because, in Play! 2, everything is compiled or packaged on the fly when 
developing. And that's awesome! 



Modifying the controller 

The actual Application controller has only one action saying that our application 
is ready. We'd now like to show in the view the well-known "It works!" message 
coming from Apache 2. 

For that, open the Application controller and simply change the value of the 
argument of index: 



Application. java x 

1 package controllers: 

2 

import play.*; 
4 import play.mvc.*; 

5 

import views.html.*; 

7 

public class Application extends Controller { 

9 

public static Result indexU { 

return ok( views , html . index . render! "It Works.")); 

12 } 
13 

14 } 
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Now let's check it in the browser: 



Welcome to Play 2,0 

«- Q 1i localho5t:9000 



It Works. 



Feels nostalgic! 

Again, no compilation or action is required to update the running code. Play! 2 does 
the boring work for us. 

There's another easy thing that can be done: changing the HTML title, which is left as 
an exercise. 

Modifying the content type to JSON 

Just to show how easy it is to deal with the content type, we'll see how to render a 
JSON response to the client. 

All we have to do is to modify the index action and nothing else. Tasks such as 
binding and creating a specific template are handled by Play! 2 for us. 

As done earlier, we'll start with the Java version: 



public static Result index!) { 

Map-;St ring, String> it Works = new HashHap<St ring, Strings-i i : 

itWorks , put ( "message" , "It Works,") 

return ok i plays. libs. Json,toJson( itWorks) ) ; 

} 



Followed by the Scala one: 

def index = Action { 

import play . api .libs . j son ._ 
Ok( JsObjectf 
Seqt 

"message" -> JsSt nng( "It Works,") 

) 

) ) 
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A quick check in the browser should disPlay! the following screenshot: 





locaLhrntiSOOO 










O localhost:9000 


{ 

message: "It Works." 

} 


Elerrenls Resources 


-' Network 










bcnpts _ iimeune 




Name 

Path 


Method 


Stat j s 

Text 


Type | 




10: 


:9000f 


GET 


20Q 

OK 


application/json 



As we can see, the browser has rendered the response as JSON because its content 
type was set by Play! with the application/ j son value. This content type has been 
automatically inferred from the data type given to the OK response (a JSON object). 
The content-type value can be checked in the browser console, as shown at the 
bottom of the previous screenshot (see the Type column). 



Browsing our errors 

Until now, all our changes have been successfully applied. Unfortunately, we can 
sometimes make errors or typos. 

The good thing is that Play! is well integrated, even for errors. This would be quite 
disappointing for some, but not much for those coming from the "classical LAMP 
stack world" for instance. 

This integration is another feature that makes Play! 2 different from the other 
Java frameworks. Everything is compiled code— views, even assets (CoffeeScript, 
LESS) — and every compile- time error is just disPlay!ed in the browser when 
reloading the page. 

This leads us to launch the application at start from the console and it'll probably be 
the last time we'll interact with this console. The only tools that a Play! 2 developer 
needs is an editor and a browser. 
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It's quite easy to imagine the kind of errors that can be made and how. So, let's 
see a few screenshots showing the result of applications presenting some of the 
errors encountered. 



Compilation error 


cannot find symbol [symbol: variable outch] [location: class controllers. Application] 


[n fh o mc' n ooots ab fa rob oo k/p lay- j b ookj'ap p . 'co n t rolle r*5 . ' A p p lkatfo n . j ava at line 10. | 


6 
7 
B 


public class Application ex.ten.ds Controller { 


9 


public static Result indexO { 


10 


return ok{views.htim.iJidex(outtrL)}; 


11 


> 


12 
13 
14 


} 


A Java error: forgot the double quotes 




_ 


Compilation error 


not found: value messag 


[n /h o me, n ooote ab rc/b oo k/p la y- j b 00 ktap p /Views /in d ex , s cala h t ml at line 4. 


1 


(SHmessage: String) 


2 






(S>maLn( "Welcome to Play 2,0") { 


■ 


<hl >{S>5essag</h.I > 


5 


} 



A Scala error: the me s S ag variable is not defined 
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Compilation error 



1 



value ids is not a member of object control lets.. Application 


[n licum- noootsab »tx book plai - jhook ccuif t our es at line 6. 


2 


# This file defines all application routes {Higher priority routes first) 


3 


^ r-JT-JT-JT-S 


4 




5 


it Home page 


■ 


GET / controllers Application. idxO 


7 
8 


# Map static resources from the .'public folder to the /assets URL path 


9 


GET /assets.''* file controllers. Assets. at(path= "/public", file) 



A routes error: the idx action doesn't exist 



Compilation error 





In /home'noriotsab/sro'book/pky-jbook/app/assets/javascripls/jbook. coffee at line 1. 



5 - 



akrt(ok 



A CoffeeScript error: forgot the last parenthesis 
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Compilation error 




.brodw is undefined 



[n Zhome'noootsab^KyboDkyplay-jbQokj'app/assets^tyfesheets/jlioDk.Jess at line 1. 



hi #id( 
|broder(5} 
ll 



A LESS error: macro not defined 



Summary 

So far, we've already taken a big step forward in Play! Framework 2 by covering 
high-level concepts, and also introduced more advanced ones in some cases. 

We tackled a whole and definitive installation of the framework itself, but with 
all of the other things that make a development environment: machine, IDE, 
command-line tool, and so on. 

We've also covered the basics that are common to all the Play! 2-based web 
applications: Java and Scala controllers, actions, and even a bit of views. 

We took the opportunity to see the whole machinery in action, and made some 
adaptations showing us the coolest features provided by Play! 2, such as compilation 
on the fly and errors shown on the browser side. 

At this stage, we know that Scala is the core language of the system; moreover, it's 
also the templating system's language. So in the next chapter, we'll see just enough 
Scala to write great templates that are easy to create and maintain. 




Scala - Taking the First Step 

Play! Framework in its second version has been implemented using the programming 
language Scala. That is, the whole core is Scala based, but APIs are available in both 
Java and Scala (without closing the doors on other JVM languages in the future). 

If we're able to keep Java as the programming language of our web application, the 
template system is still a Scala one. Hopefully, the scope of a templating system 
shouldn't include business logic, as a result of which the needs are often quite simple 
and recurrent. 

This chapter's intent is to provide a very high-level view of what Scala is, without 
going deeper into the details. Following are the topics that will be covered: 

• An introduction to what Scala is 

• Scala expressions versus Java statements 

• A taste of the Scala type system 

• How to get the best from sequences in Scala 

• Partial application of functions — a simple and powerful tool used 
for composition 

[r%~X The examples will be presented both in Java and Scala to help you to 
intuitively understand the concepts presented in the Scala version. 
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Introducing Scala 

Scala is such a complete language that it could be defined in several ways. However, 
we'll try to summarize it with some shortcuts. Scala is a complete language meant 
to optimize development time and code. That's why the name Scala was chosen, 
which stands as a mix of scalable and language. The name signifies that the underlying 
concepts of the language are growing well with application needs or complexities. 

Why Scala can be defined as optimized is mostly because of the paradigms on which it 
relies and the ones it offers. 

In short, Scala code is more concise and elegant, and can be less buggy simply 
by smoothly combining the features from an object-oriented language and a 
functional one. Very roughly, take a blender, drop in Java and Haskell, and 
you'll get a taste of Scala. 

In the coming sections, we'll see the common features of Scala. 



Expressing your code 

Scala is a language that uses expressions wherever it makes sense— which is 
everywhere. Indeed, an expression is an instruction that returns something. So, 
every construction is expected to return a value. That includes if -else, while, 
for, and so on. 

Let's see them in action and see how helpful it can be. In order to ease the readability 
of the code, we'll see each example in both Java and Scala, enabling comparison on 
the fly. 



If-else 

An if-else statement in Java is a way to alter a behavior based on a predicate, 
which can be composed of repetitive if-else blocks. Scala has exactly the same 
objective for if-else but will always return a value. The following screenshot 
shows some examples: 
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2 


ige cornparxson 


2 


comparison 




3 


public class IfElse { 


3 


object IfElse { 




4 


//NOTE: we don't use return within branches for 


4 






5 


// bes-practices reasons 


5 






6 




6 






7 


//176 chars 


7 


//91 chars 




8 


public static String cat ego ry ( int age) { 


8 


def category[age:Int] = 




9 


String result = nullj 


9 


if I age < 181 { 




10 


if (age < 18] { 


1G 


"Young" 




11 


result = "Young"! 


11 


} else { 




12 


> else { 


12 


"Old" 




13 


result = "Old"; 


13 


} 




14 


> 


14 


//or E»cn : 59 chars 




15 


return result; 


15 


def cat egory2( age : Int ) - if 


(age < 18) "Young" else "Old" 


16 


) 


16 






17 




17 






IS 


//272 chars 


18 


//16S chars 




19 


public static String finestCategory( int age] { 


19 


def finest Cat egoryt age : Int! 


= 


2G 


String result = null ; 


2Q 


if (age < 5) { 




21 


if (age 5] { 


21 


"Kid" 




22 


result = "Kid"; 


22 


} else if (age < 18) { 




23 


} else if [age < 18) { 


23 


"Young" 




24 


result = "Young"! 


24 


} else { 




25 


> else { 


25 


"Old" 




26 


result = "Old"; 


26 


} 




27 


} 


27 






28 


return result; 


28 






29 


> 


29 






30 




30 






31 


//446 chars 


31 


//332 chars 




32 


public static String qualified! int age, short kind) { 




def qualified! age : Int . kind 


Short) - 


33 


String q = null ; 




(if (age < 2) { 






n -f fane =■ 1 1 -f 

it ^ age ij i 








35 






> else if (age < 5) { 




36 


> else if (age * 3) { 


36 


"Kid " 




37 


q = "Kid "; 


37 


} else if (age < 7) { 




38 


} else if (age * 7) { 


38 


"Young " 




39 


q = " Young " ; 


39 


} else { 




40 


> else { 


4G 






41 


q = "J 


41 


)! + 




42 


> 


42 


(if (kind == 1) { 




43 


String g = null ; 


43 


"Girl " 




44 


if (kind == 1] { 


44 


} else if (kind == 2] { 




45 


g = "Girl"; 


45 


"Boy" 




46 


} else if (kind == 2) { 


46 


} else if (kind == 3] { 




47 


g = "Boy"; 


47 


"Dog" 




48 


> else if (kind = 3) { 


48 


> else { 




49 


g - "Dog"; 


49 


" Cat " 




50 


> else { 


5E3 


>l 




51 


g = "Cat"; 


51 






52 


> 


52 


) 




53 


return q + g; 








54 


> 








55 










56 


} 









• For those hungry to copy paste, this code is also provided in I 

%/\ the code files of the book. It's recommended that you look at the I 
sources but try them yourself first. I 

If we focus on the first example, we will see that the Scala version looks like the 
corresponding if -else statement that Java has using ? and : . However, the Java 
version doesn't scale very well and you must embed them deeper and deeper, 
whereas the Scala code remains easily readable. Another good feature is that no 
extra temporary variable is required in the Scala version. 
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Switch/Pattern matching 

One of the greatest features that Scala brings is its pattern matching against 
structures (even for complex/multilevel ones). Where Java's switch statement 
gets stuck with integer and enum data types (string for Java 7), Scala provides 
pattern matching. 

Pattern matching can be seen (roughly) as a general switch statement that returns 
a value. What we provide is an object and some patterns (type, possible values, and 
so on) against which Scala will try to detect a match, stopping at the first match or 
throwing a scala . MatchError exception if there is no match. 

The following screenshot shows some examples: 



'arte rn Match ing.jav a X 
package comparison: 

public class PatternMatching { 

//132 chars 

public static String switchOnlr 
String result = null; 
svitch Ualuel { 

case I! result = "one" 

break; 
case 2: result - "two" 
break; 

case 3: result - "threi 
break; 

case 4: result = "-four' 



PatternMatchin 



f/71S chars 

public static class [ 
public int ij 
public boolean b 

public Data (int : 



iss Data[i:: 
:hOnDcmainO! 



} 

)lic static String checkDonainObj ect ( Data data) i 
String result = null; 
if ( Idata.b] { 

result = "disqualified"; 
} else { 

switchldata.il { 

case 1 result = "first " : 
break; 

case 2 result - "second"; 
break; 

case 3 result - "third"; 
break; 

default: result = tdata.i < 1QQI ? "cor red 



"disqualified" 



The code is pretty straightforward; the Java version of the switch statement is 
very reductive whereas the pattern matching of Scala can introspect a lot of things, 
including structures, and strings that use regular expressions. 



Chapter 2 

The important part of pattern matching in Scala is its flexibility. In the second 
example (Scala version), we saw five interesting things appearing: 

• Data is a case class, a class that can be matched on and that declares its 
constructor inline 

• The pattern matching is able to match within structures (Data (l , true)) 

• The fourth case is mapping the integer to a new variable named x 

• The x variable can be checked further into a case guardian (x < 100) 

• If a value is not of interest to us at some point, we can use _ to discard it 

But apart from all this, what is very noticeable is the readability of the code. Where 
Java's needed several levels (chaining if -else and/ or switch statements), the Scala 
one remains linear. 



Generic types 

What Scala adds to Java is a stronger type system, including generics that can span 
several levels, which means that you can have a generic of generics, and so on. 

We won't cover the Scala type system here as it would take the rest of the book to get 
the gist of it, but we'll take an overview of what is often needed in templates when 
declaring the arguments they can take. 

The two major differences between the Java syntax and the Scala syntax are 
as follows: 

• Scala declares generics between square brackets ([...]) whereas Java does it 
between angle ones (<...>). 

• Java allows the declaration of a generic extending another type using the 
extends keyword (Juice [F extends Fruit] ). Scala generics can be lower 
and upper bounded using operators > : and < : , so where Java generics are only 
able to declare upper bounds, Scala can declare lower constraints as well. 

[r%Ti I n Scala, a type can follow the hierarchy of its generic. For example, 
^yc^ a list of apples is also an instance of a list of fruits. 
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Let's see some examples: 



____________ _ _^ 

1 package comparison 

5 ob] ect Generics { 
//4S chars 

case class NonEmpt yList [ G] ( h : G, rest : List [ G] ] {> 



Generics.java 



package comparison: 

import j ava , ut il , List ; 
class Generics i 
//204 chars 

class NcnEmtpyList<G> ■{ 
public 6 head: 
public List<G> rest; 

public NonErntpyListlG head, Li_t«G» rest! { 
this . head = head; 



//351 chars 
interface Ser { 

Bytel ] export [ ) j 

} 

interface Writeable=?El extends Se r * { 
void write | El ser)j 

} 

abstract class Adapt ableWriter<W extends Writeable<El> 
public W target ; 

public abstract ET adapttEl el; 

public void out I El e!l i 

target .write(adapt(e) I j 

} 



mulate a Function. . . Simila 
rface Functionl^A, B? { 
B apply! A a) ; 



i the Command Patte 



} 

//WILL FAIL AT COMPILE TIME 
// interface Functor*F-*?|» { 

// <A, B> F<B> fmaj;(F<A> a, Functionl<A, B> fjj 

// ) 



//277 chars 
trait Ser { 

def export : Array [ Byte] 

> 

trait Writeable[El Ser] { 
def write(el:El) 

} 

trait Adapt ableWriterlW <: Writeablel El ] , El 
def target !W 

def adapt! el : El I : El 

def n_t(eliEl! - target .writetadapt ( el ) ] 



//WILL COMPILE -- now, search the web fi 
trait Functor[F[J] { 

def firapIA, BHaiFU], f:A=>B):F|B] 



} 

//an instance of a Functor.., Scala provides it for all traversal 
object ListFunctor extends Functor! List ] { 
def firap[A,B] (a: List [A] , f:A=>B) - 
for (item <- a) yield f(item) 

J 



Let's review the examples to figure out where the differences are and how Scala can 
offer more. 

The first example is quite easy to get. We define a list that cannot be empty. For this 
purpose, we just defined a type that is instantiated using an element and a list. Of 
course, the list can be composed of anything of the same type; that's why it declares a 
generic G. 

As we can see, the only difference (except the concision of Scala using case class) 
is the syntax used for declaring the generic. 

The second example defines a type that can output adapted elements. The output 
w will be written with a version of the element s which w knows how to serialize — 
thanks to the adapt method. 



[48] 
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The adapt method shows how to declare several bounded generics that are allowed 
using the inherited methods. Here again the syntax is the only difference; we used 
< : in Scala rather than extends which we used in Java. If we pay more attention to 
the type declaration, we will notice that the trait keyword appears in Scala whereas 
interface and abstract class were used in the Java code. A trait can be thought 
of as the conceptual union of an interface with an abstract class because they can be 
mixed together (like interfaces) and can define implementation (like abstract classes), 
but they cannot be instantiated (like interfaces and abstract classes). 

The last example shows the limit of the Java type system. In Java, we started by 
defining Functioni, which is just a "classic command" that accepts one parameter, 
that has both the parameter's and the result's types as generics. 

This wasn't necessary in Scala because functions are first-class citizens (a function can 
be treated as an object). So what we can do out of the box is to declare a parameter as 
being a function such as A= >B, which means that a function taking one parameter of 
type A will result in a value of type B. So, a function in Scala can be passed to other 
functions because they are "thinkable" as variables. 

Then, we tried to define a high-order type called Functor. In short, it means a 
functor should use generics such as Functor<F<?>> that are generics themselves. 
Two things that Java doesn't like, the first being the interrogation point which is not 
permitted at this depth (second generic level). The second thing is the real problem 
and is the fact that Java doesn't support embedded generics at all. Even if the f map 
method is syntactically correct, we cannot use it efficiently because the F type cannot 
be declared correctly. 

Switching to the Scala code now, we declared Functor [F [_] ] that compiles 
perfectly. The _ is present in the definition of F because, at this level, we don't care 
what the inner type of F is; we just need to assert that F has a generic. 




A functor is basically something that can adapt a value in a container 
without touching the container. It becomes obvious when looking at 
the Scala code that the f map method of ListFunctor enables us to 
adapt the element of a list by returning them in a list. 
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Iterating over a sequence 

Scala fits pretty well with list manipulations. Indeed, it facilitates their usage by 
defining a lot of methods that enable a lot of behaviors, such as filtering elements or 
grouping them based on an aggregation value. There are tons of such methods, and 
actually, if we need something to do something with a sequence, it should already 
be defined at http : / /www . scala- lang . org/ api /current/ index . html # scala . 
collection . Seg. 

In the coming sections, we'll cover the most useful sequences when building Scala 
templates. First of all, let me just point to the fact that in Scala, when we think List 
we mean Seq. 

Function - foreach 

The foreach method provides a way to iterate over a sequence and apply a given 
function to each item. In object-oriented programming, we can think of it as a visitor 
pattern on a flat list. 

The result of foreach is Unit, which is the Scala version of void in Java. 
The following screenshot shows how to use it: 



/ Foreach java x \ 




package comparison: 

import j aw a . irt il , List ; 

4 import j ava . util , Array List ; 

5 import j ava . util , Arrays; 

t public class Foreach { 

8 

static List «;Integer> list - Arrays . asList ( 1, 2, 3, 4, 5); 

ia 
n 

12 interface FunctionQsA* { 
void applyf A a j ; 

14 > 
15 

public static void f oreach( FunctionO<Irrteger> f] { 
for (Integer i : list] { 
f .apply(i) j 

19 > 

20 > 

21 //22G chars 

public static void printSeqO { 

foreachlnew FunctionO«:Integer>( ) { 

public void apply( Integer element) { 
System out . p rintl n ( el ement ] j 

26 > 

27 }]; 

28 } 
29 

30 

31 } 


1 package comparison 

4 
5 

6 object foreach { 

7 
8 

9 val seq - Seq( 1, 2, 3, A. 5) 
1G 
11 
12 
13 
14 
15 
16 
17 
18 
19 
2Q 

21 //S7 chars 

22 def printSeq = 

seq, foreach { 

element => printlnl element j 

25 } 

26 

27 

} 
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As we can see, the Java code is less elegant and requires "boilerplate" (a Functiono 
implementation), but it explains well what the Scala code does. 

In Scala, we didn't declare the data type to be Int due to type | 

VSt js. inference. Type inference stands for the mechanism that allows I 
a compiler to discover what the type of a variable is. I 



Function - map 

The map method is pretty much like the f oreach method, but instead of returning 
Unit, map returns a new sequence composed of the results of the function applied 
to each element. So it provides a way to adapt each element, while keeping them 
arranged in a sequence. 

The following screenshot shows how to use it: 



J Map. java a \^ 




1 pack age comparison : 

J import ] ava , Lit il , List .: 
4 import j ava , util , ArrayList ; 
import j ava , util , Arrays; 

public class Map { 

e 

static List<Integer> list - Ar raj's . asList ( 1 , 2, 3, 4, 5); 

IB 
11 

12 interface Functionl-tA, B> { 
B apply | « a] j 

11 > 

15 

public static <E> List<B> irapi Functionl^Irrtegerj B> f) { 
List<B> result = nev ArrayList <B>( i ; 
for (Integer i ; list) { 

result .add(~f,apply(i) ) ; 

2B > 

return result; 

22 > 

23 //233 chars 

public static List<Double> squaredSeqf) { 

return map [new Functionl<Irrteger, Doubles ) { 
public Double apply! Integer element] { 
return Hath. powl 2, element); 

2B > 
29 » : 

£> 

32 > 


1 package comparison 

3 
4 
5 

5 obj ect Map { 

8 

9 val seq = Seqll, 1, 3, 4, 5] 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 

21 
22 

23 //4Q chars 

def squared5eq = seq . map( mat h . pow[ 2, )] 

25 

26 } 



Here again, the Java version is more verbose, but reading the code would help you to 
understand the Scala version better than if it was explained in words 



In the Scala version, we can see another use of the underscore (_) 
character. Here it represents a placeholder for the current function's 
argument. It's the more concise way to define inline functions. In 
this case, it is the same as having (x : Int ) = >math . pow ( 2 , x) . 
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Function - filter 

The name of this function is self-descriptive; it allows us to iterate over a sequence 
by applying a given predicate on each item, and returns a sequence of all the 
valid elements. 

Let's jump into the code directly: 



Arrays. asListll, 2, 3, 4, 5| ; 



Filter-java X 
package comparison: 

2 

import j ava , util . List : 
import j ava , ut il . ArrayList : 
import j ava , ut il . Arrays; 

6 

public class Filter { 

8 

static List<Irrteger> list - 

.0 

interface Functionl-sA, B> { 
B apply A a) j 

3 } 



public static List-elrrtegers- filter! Functionl-elrrtegerj Boolean:* pi { 
List<IiTteger> result - new ArrayList<Irrteger>( j ; 
for [Integer i ; list] ■£ 

if (p.apply(i)) result , add( i) j 

> 

return result ; 

1 

//2Q7 chars 

public static List<Irrteger> event) ^ 

return filter! new Functionl<Integer, Boolean>( ] {. 
public Boolean apply! Integer i] { 
return i % 2 == 0; 



} 



Rlter.scala X 

1 package comparison 



object Filter] { 

7 
8 

9 val seq - Seq(l, 2, 3, 4, 5) 

10 
11 
12 
13 



//29 chars 

def even - seq . f lit e r ( _%2==Q] 



So short and so helpful, isn't it? 

The code is pretty straightforward and self-descriptive. We ask the seq sequence to 
be filtered using a predicate function that tests if the integer is even. So the result will 
be a new sequence of all the even elements in seq. 



Function - exists 



This exists method is like contains in Java, but it uses a comparison function 
rather than using equals. 
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The following screenshot shows how to make use of it: 



f Ek 






\W Exiats.acala X 




package comparison: 




package comparison 






import j ava . ut il . List .: 


J 






4 


import j a vs . ut il . Array List ; 


4 








import java.util. Arrays; 


5 






e 

7 


PL 


nlic class Exists { 




object Exists { 




8 
9 




static List-dlntegers- list = Arrays . asList ( 1, 2, 3, 4, 5); 


9 






10 






10 


val seq - Seqll, 2, 3, 4, 51 




11 




interface Funct ionl^A, E> { 


11 






12 




B apply(A a) ; 


12 






13 




} 


13 






14 






14 






15 




public static Boolean exists 1 ' Funct ionl-clnteger. Boolean* p] { 


15 






16 




■for [Integer i : list) { 


15 






17 




if (p.apply(i)) return true; 


17 






18 




} 


IS 






19 




return false; 


19 






20 




> 


2Q 






21 




//203 chars 


21 


//36 chars 




22 




public static Boolean biggerThan5( ) { 


22 


def biggerThan5 = seq exists [ 




23 




return esists(new Funct ionl-tlrrteger. Boolean?- 1 \ { 


23 






24 




public Boolean apply! Integer il { 


24 


J 




25 




return i > 5; 








26 




} 








27 




»; 








28 




} 








29 














} 











It's that simple! 

Looking closer at the example, you'll see that the Scala version doesn't 
use dots to separate the method from the caller; that's the point-less 
notation. This feature could also be called the distraction-zero notation, 
which is a welcome feature when creating a DSL. 




Function - find 

One of the common tasks with sequences is to retrieve an item that must match a 
predicate. Scala has the find method for that, and it has a specific behavior when 
none of the elements match. 

This method will iterate over the sequence by checking the predicate and return an 
Option [El] value in all cases. An Option is a special type in Scala that is meant to 
represent a value or non-value; it is explained as follows: 

• object None extends Option [Nothing] : This extension of Option simply 
represents a non-value. It'll be returned if no element has been found. 

• case class Some [El] (v: El) extends Option [El] : This extension of 
Option represents a wrapper over a value (v). 
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This type enforces the definition of a variable to be potentially undefined. We can 
also think of None as a type-safe null in Java, and it can be used as an alternative to 
exceptions. Indeed, if we have a function that parses string as int, it could return 
an Option of type int rather than an int type, so the user will be able to react to bad 
strings rather than catching the exception. 

It's time to see it in action: 



Rnd.jaua 


IV Rnd.scala x ^^fl 






package comparison: 




package comparison 






i m p o rt j a va . ut il . List j 


3 








impo rt j aua . ut il . Ar rayList ; 


4 








impo rt j ava . util . Ar rays j 


5 






6 




6 






7 


public class Find { 


7 


object Find { 




S 
9 


static Listt;IrTteger> list - Ar rays . asList ( 1 , 2, 3, A, 5] j 


8 
9 






10 




1G 


val seq = 5eq( 1, 2, 3, 4, 5] 




11 




11 






12 


interface Functionl^A, B> i 


12 






13 


B apply ( ft a | j 


13 






14 


> 


14 






15 




15 






16 


public static abstract class 0ption=:A> { 


16 






17 


public Boolean isDefinedf) { return this instanceof Sone: ) 


17 






IS 


> 


18 






19 


public static class None<A> extends Option-*;*;* {} 


19 






2Q 


public static Noneulrrt ege r> Nonelnt - new None<Integer>( j : 


20 






21 


public static class Some<A> extends 0ption<A> { 


21 






22 


public A v; 


22 






23 


public Soire[A if) { this.u = } 


23 






24 


} 


24 






25 


public static Option<IrTteger> find 1 Functionl<Integer, Boolean:* pi { 


25 






26 


for (Integer i : list) i. 


26 






27 


if (p.apply(i)) return new Some-dint ege r:» ( i) j 


27 






28 


} 


28 






23 


return Nonelnt: 


29 






30 


} 


30 






31 


//2Q5 chars 


31 


//17 chars 




32 


public static Option<Integer> fetch3( ) { 


32 


def fetch3 = seq find (_ == 3) 




33 


return findlnew Functionl-tjlnteger, Boolean>( ] { 


33 






34 


public Boolean apply( Integer i) { 


34 


> 




35 


return i == 3; 








36 


> 








37 


}); 








38 


> 








39 










40 


J 









As the Option structure is not available in Java, we had to define it (in some way) in 
order to mimic as much as possible of the Scala code. 

[ - Java 8 has introduced a new type called java .util . Optional | 
VSlJs. that does much the same. But it would have been cumbersome to I 
implement our example with Java 8. I 
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Function - apply 

The last method we'll see in this section is the apply method. The Scala compiler 
has a special behavior for the apply method because it's not mandatory to call 
it explicitly. 

Indeed, when a type declares an apply method, we'll be able to call its instances as if 
they were functions. See the following screenshot for an example of this: 



case class Kenaerentempiate : hue, arguments : Any*j t 




def render! ): St ring = //.., 




def apply (writer :Writer) = writer ,write( render! ) 

} 


getBytes( "UTF-8") ) 


val myRenderer = Rendererl new File!/*...*/), 1, "ok" 


t rue) 


myRenderer(new Out put St reamWrit e r ( Syst em . out ) ) 




myRendereri new FileWriter( /'+ ..,*/)) 





What is shown in the previous screenshot is an example of how we can create 
a template that has been rendered by giving a file and a list of arguments. It 
has a render method that renders the file using the given parameters, which is 
called within the apply method. As the goal of Renderer is to create a usable 
representation of a template, it seems obvious that we should be able to call this task 
easily and in a readable manner. This is what is achieved in the two last statements. 

[r^STX arguments : Any* is the Scala way to declare a varargs 
^fci^ Object. . . argument, Any being Java's Ob j ect. 



Going back to the sequences, we can now imagine what the apply method 
of a sequence would be, given that it takes an int type — it's the index of the 
requested element. 









% 


W Apply.java X 


\W Applyscala X 










.. 


package comparison; 




package comparison 






2 






import ] ava . util . List .: 


3 




A 


import j ava . util. . Ar rays ; 


4 








5 




6 


public class Apply { 


6 


object Apply ■[ 


7 




7 




S 






iral seq = Seq( 1, 1, 3, 4, 5] 


9 
10 




10 




11 


Integer third = list . get ( 2) ; 


11 


val third = seq(2l 


12 




12 






} 




1 
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Other interesting functions 

Sequences (iterables) define plenty of methods that are very useful and, truly, cover 
every use case that we'll encounter while dealing with them. 

Following are some other functions that you might want to have a look at some time: 

• partition: Based on a predicate, this function splits the sequence in two 

• collect: This function mixes map and filter at once 

• groupBy: It takes a function that must produce the key values of a resulting 
map that packages all elements having the same key value 

• sliding: This packages the elements using a window and slides it over the 
whole sequence (it is graceful in dealing with items that need to be shown in 
a predefined number of columns, for example, a gallery) 

• length: This returns the number of items in the sequence 

Partial application 

In simple terms, a function in Scala can declare several blocks of parameters. Thus, 
a partial application of a function in Scala either leaves at least one block without 
values or one parameter without a block. In this section, we'll only talk about the 
first case. 

Actually, filling up the last parameter block will create another function that takes 
a number of block parameters and decreases them by one. Repeating this until no 
blocks remain will result in the whole function being applied. 

As this Scala feature will extensively be used when creating a layout of our future 
templates, it's important to grasp this concept. Hopefully, it isn't hard; seriously! 
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Let's see an example of such a partially applied function: 

I ' Currying. scala 



1 package comparison 

2 

3 import seal a . coll ect ion , immut abl e . {Hap => Map_, _} //because of the comparison . Hap 

4 

5 object Currying { 

6 

yal messages = Map_( 
"en" -s> Map_( 

"welcome" -> "Hello!", 

10 "bye" -■> "See Ya ! " 

11 ). 

12 "fr" -> Map_( 

"welcome" -> "Bon] our!", 

14 "bye" -> "A Plus ! " 

15 ) 
16 

17 ) 
18 

def showHessage( msg : St ring) dang : St ring) = println( messagestlang) ( msg) ) 

2Q 

21 //those following function are partially applied (note the vats) 

22 val showInEn = showHessagei_: St ring) ( "en" ) 

23 val showInFr = showHessage!_: St ring) ( "f r" ) 

24 

25 //call it will output Hello! in the REPL 

val showWel comelnEn = showInEn ( "wel come " ) 
27 //call it will output Salut^ in the REPL 

val shovWelcomelnFr = showInFr( "welcome" ) 

29 

30 } 




First of all, we defined a map of il8n messages where a map is conceptually the same 
as j ava . util . Map, that is, a key -value pair type. 

Then we defined a function (showMessage) that is able to retrieve an 
internationalized message based on its key. We can see that the function name is 
followed by two blocks of one parameter each. 

The next two vals are partially applied versions of this showMessage function, and 
they are actually vals but their value are functions. These versions are the common 
functions that are used to show messages either in English or in French. 

The last two vals are also functions, but they are fully completed versions of 
showMessage, that is, with a complete set of parameters. Calling them will simply 
print the relevant messages without computing them any more. 
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Summary 

In this chapter, we have reviewed parts of the Scala language that we'll need 
in further sections when creating our web application's views using the Scala 
templating system. 

We first introduced the language itself. Then we moved to the definition of an 
expression, studying some expressions in detail. We also looked at some ways with 
which Scala allows us to manipulate sequences. Well actually, we've seen enough 
to tackle most cases encountered when creating views for sequences (for instance, 
showing a list of users grouped by the first letter of their last name). We've seen how 
we can transform the elements into a new sequence, filter them, check their existence, 
and so on. 

Such sequences are used most of the time with generics (especially when domain 
modeling is used with a top-level interface), but it's not a big deal for us as we can 
now declare and use generics in Scala. 

Finally, we are able to create functions that result in functions, which in turn result in 
other functions, and so on. This will help us when creating templates and especially 
for creating layouts with them, which will be discussed in the next chapter. 




Templating Easily with Scala 

Play! Framework 2 is a web framework, and so is meant to create web applications. 
A web application is an application that presents an interactive interface through a 
web browser. But the browser might not be the only client of such an application, 
because data created while using it could be used by other applications (that's web 
integration). And so, very often, the server side of a web application is also exposing 
data through web services. Which leads us to the need, as developers, to not only 
generate HTML pages, but also TXT pages, XML pages, and so on. 

Play! 2 provides a powerful way to create all such external representations of server- 
side data: a type-safe templating system based on Scala. 

In this chapter, we'll cover the following topics: 

• Understanding exactly what a template is 

• Looking at where and how they are declared 

• Creating a reusable HTML template 

• Combining dynamic data with templates 

• What Play! 2's compiler will generate 

• How to combine several templates into a single one (layout) 

• How to skin templates 

Shape it, compose it, re-use it 

This first section will concentrate on what a template is, its structure, and 

its features. We'll see how it can help us to easily create views in a composable 

and sharable fashion. 
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Creating our first template 

A template in Play! Framework 2 is basically a file with a specific extension that 
commonly resides under the views package. So, a template filename always has the 
following pattern: 

<template-name> . scala . <content-type> 
It is composed of the following: 

• A template name, which must be formatted like a variable (for example, 
listcontainer). This will be used to reference it in the controllers. 

• A first extension part, . scala, which is always the same. As stated earlier, 
templates are Scala-based. 

• A second extension part, which is the real type of the data. Out of the box 
types are . html, . xml, and . txt, but Play! 2 is extensible enough to enable us 
to add new ones. 



OPEN FILES 


^NstCo ntainer.5cala.html X 


listcontainer. scala. html 




FOLDERS 


1 


V play-jbook 




► .settings 




W app 




comparison 




► controllers 




V views 




indeK.scala.html 




listContainer.scala.h 




rnain.scala.html 




b- rnnf 





Play! 2 will detect these files based on the pattern and will compile them into 
functions that will be available for the controllers or other templates. 

• While the structure was rigid in Play! 1, this new version enables us to 

^% \ create our files wherever we want. But views is a good convention— to 

have everything in one place. However, files still have to match the pattern. 

So let's create a new template named listcontainer that renders HTML content. 
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Structuring it 



A template is expected to respect a certain structure that starts with the parameters 
list. As a template will be compiled into a function, it can accept parameters just as 
any other function in Scala. 

When declaring a Scala function, we need to first give it a name— the filename is the 
function name— and only then can we declare its parameters. So, logically, this is the 
first line of all templates. 

These parameters are declared in exactly the same way as for Scala functions — that 
is, between parentheses and paired by the name and type separated with a colon — as 
shown in the following screenshot: 



The only thing that differs is that we need to use the magic character (@), because 
it's Scala code in a template. To illustrate this, we'll add two parameters to our 
listContainer template. 

It's pretty easy. We've just defined our template as a function that takes the following 
two parameters: 

• level: It is of type I nt 

• items: A sequence containing strings 

At this stage, the Play! 2 compiler will make available to us a function with the 
following signature: 

def function ( level : Int , items : Seq [String] ): Html 

Play! 2 has worked out that the file is an HTML template, from the second extension 
( . html) of the template name — that is, the Html result type of the function. 



Now that we have created a template with its parameters, we will define a function 
that produces HTML, but an empty one! 

The content of a template is inserted into the file directly after the parameters' 
declaration. 



V 



li5tC0ntainer.5cala.html X 

@U.evel : Int , items : Seq [ St ring] ]\ 




Adding content 
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In our case, we're about to create an HTML structure using HTML notation (the same 
happens for JSON, XML, and so on). So let's create some content in there: 



li5tC0ntainer.5cala.html X 



1 @(level : Int , items : Seq[ St ring] ) 

2 

<hl>Here we go ! </hl> 



Now, the listContainer function will produce a small HTML instance of this 
simple excerpt. 

Wait! It's not really useful, because it does nothing with our parameters. That's 
where Chapter 2, Scala - Taking the First Step, comes to our rescue. We'll use Scala 
to create some relevant content based on the server-side data. 



' listC0ntainer.5cala.html x T index.5cala.html 


X 


r \ 




1 @( level : Int , items : Seq[ St ring] ) 




2 




<h@level>Here we go ! </h?level> 




4 




5 <u\ id="list@level " st yle=" margin -I eft : 


@{5*level}V > 


6 




@items.map { item => 




<li>@it em</"li> 




9 } 




10 




11 </ul> 





As you can see, we adapted the template to use the level parameter —which is of the 
type int — to change the flow for both the title and the list of rendered items. We used 
it to change the header level (hi, h2, and so on) and to adapt the style attribute. 

Then we used the map function on Seq to produce a new sequence of HTML blocks, 
each of them being the representation of an item. 
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Composing templates 



In order to see our listContainer template in action, we could define an action 
and a route that asks to render it; but what we'll do instead is call this template in 
our index . scala . html template. That's how layout is achieved in Play! 2. See the 
following screenshot: 



listContainer.scala.html X ndex.5cala.htm 

@!message String] 

@main[ "Welcome to Play 2.Q") { 
*:hl>@rnessage*:/hl> 

@list Container! ?, ?] 



import play,*; 
import play , mvc , *j 

import views . ht ml *; 

public class Application extends Controller i 

public static Result index! ] { 

return ok« index . render! "It Works!")); 

} 



The previous screenshot shows how to call a template from within another one, 
which is basically calling a function from within another function. 

_ • The screenshot also shows the action that must render the 
^\ index page; it has been covered in Chapter 1, Getting Started 
with Play! Framework 2. 

So the index . scala . html template/ function is first declaring a single parameter 
message, followed by its body/ definition that starts by using the main function with 
two parameter blocks. 

• The first parameter is for the title 

• The second parameter is actually a block of code that is enclosed within 
curly braces 

y Actually, it's a Scala feature. A parameter might be within 

^% \ parentheses or within curly braces. The latter enables the 
' parameter to be a block of code. 

In this case, we defined an HTML block that refers another template, 
listContainer, just as any other function. That's how templates are 
combined in Play! 2. 

So far so good? Well, not exactly. Looking closely at the listContainer call in the 
index . scala . html template, we'll see that it still needs some parameters. 



Let's see how to fill them. 
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Passing data structures 

Having composed our templates (index, scala .html using listContainer), we 
need to do two more things: 

• Adapt the parameter list of index .scala . html using curried parameters 
(two sets of one parameter in this case) 

• Adapt the index action in the Application controller to match the new needs 
First we will modify the template to allow access to data usable by listContainer: 



NstContainer.scala.html X Y index.5cala.html X 
/ 

1 @(message: St ring) (level : Int , list : Seq[ St ring] ) 

2 

3 @main( "Welcome to Play 2. 0' I { 
*:hl:=-@m e s s a g e ■■■ hl> 
@1 ist Container (level , list) 

} 



For that, we added a new parameter block that adds the required data. 
A new parameter block is not mandatory; it's just a good way to have a clear 
distinction of what is needed by what. Then the data is simply re-used within 
the listContainer call. 



If we try to hit the index . scala . html page right now, we'll see the same error 
screen as the following screenshot: 



Compilation error 




G localhost 


Compilation error 


render(java Jang. String, int, &cala.cDllectiori.Seq<java Jang. St ring"-) in viewB±tmlJnde.x cannot be applied to Java Jang. String) 


[n . Ti o m&'nooots ab fs rcfb do k .p lay- j b ook'ap p .'ton t r oik* rs . 1 A p p bcatk) n . j ava at line 11, 






a 


public class Application extends Con troller { 


9 
10 


public static Result index( ) ( 


11 


return ok(lnde?i|render("IL Works!"}}: 


12 


.} 


13 




14 


( 
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This happens when we use our Java project and we notice that the template 
compilation failed because parameters are missing in the template call from 
within the Application . j ava#index action. 



Currying is not allowed in Java; but our template function is. 
However, it is not a big deal. Indeed, some magic happens in order 
to adapt our Scala function by taking two blocks of parameters into 
a Java render method, which takes all parameters collapsed in a 
single parameter block. 



So, let's go to this action to pass it an integer value and a collection of strings: 



listContainer.scala.html >C V index.scala.html JC '/ Application. java 



3 import play.*j 

4 import play.mvc,*; 

5 

:" import vievs.html.*; 

8 public class Application extends Controller 1 

9 

public static Result index() { 
irrt level = 1; 

java. util. List <String> list = java. util.. Arrays, asList ( "me" , "and you?'\ "tea", "for tvo?")j 

13 return ok( index . renderf "It Works!", level, list))] 

14 } 
15 

16 } 

17 

18 



Now let's check again in the browser: 



Compilation error 


rmdOT{java.lang.5tring,int.5cala.collmion.Seq^java.la.[ig.String>) in views. html. index cannot be applied to fjava.laog.String,iTit,java.utiLList<java.lang.5tring^) 


[n home in: Isab sr( book -jbook npp i on trailers Application java at line 16. 


12 
13 


public static Result indexO { 


14 


int level - 1; 




java. util. LLSt<5tring'- v LLst = java.util. Arrays .as Llst("™", "and you?", "tea", "lor two?"); 


m 

17 


return ok{Lnde\|render{"lt Works!", level, list}}; 

i 


18 




19 


i 



Ouch! Interestingly, in the Scala template we used a Scala collection to represent 
our data; but going back to the controller (Java in this case), we're unable to use the 
classic j ava . util . List collection to create our server-side data. 
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In order to solve this problem, there are some conversion utilities available in 
Scala, which can be found in scala . collection. JavaConversions. This class 
provides a static method that will help us in converting our Java List to a Scala Seq: 
asScalaBuf f er. 



I istContainer.se a la..html X 



V 



indeK.5cala.html 



Application, java 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 



import play.*; 
import play.mvc,*; 

import vievs.html,*; 

import static scala. collection. JavaConversions | 

public class Application extends Controller { 

public static Result indeaU { 
int level = 1; 

java. util. List <String> list = java. util. Arr ays. asList ( "m e" , "and you?" J "tea", "for two?"]; 
return ok( index , rendert "It Works! ", level, |asSCBlaBU"tfer |(li5t ) ) ) j 

> 



Normally, everything should be OK now and we should get the following screenshot: 



Q H -JO Iocalho5t:9000 



It Works! 



Here we go! 



• me 

• and you? 
» tea 

• for two? 



Actually, since this was only an example we could have used 
j ava . util . List directly in the template. But as the Play! 
2 project could involve Java or Scala code, it's better to use a 
dedicated language for the templates. 



] 
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Playing around 

Now that we have a good understanding of how a template can help in creating 
views, we'll try to adapt our templates to make them interesting. The idea is to fix 
all the concepts seen so far in your mind. 



Laying out 



In the first section, we created a listcontainer template that was able to render 
a sequence of strings into a ul HTML element. In this section, we'll adapt it a bit 
to enable a header and a footer around the list. For that, we'll use currying and the 
internal HTML representation of Play! 2. 

So, all we have to do is redefine the listcontainer function to take two new 
parameter blocks, header and footer, which are HTML excerpts. 



li5tCc1ntainer.5cala.html X 



1 

2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 



index, scala. html 



@(header:Html) (T.e«el : Irrt , items: Seq[ St ring] ) ( footer : Html j 

■=div styT.e="margin-left : @{5*T.eveT.}V> 
@header 

<ul id= "1 ist @level " > 

@items.map { item => 
<li>@iten</li ■ 

> 

@f oot e r 
</ div> 



As expected, the type of these new parameters is Html, which is the internal 
representation of HTML blocks in Play! 2. Then, we use them right before 
and right after the block disPlay!ing the list, and we remove the previous 
hi element (which was saying Here we go!). 



We also encapsulated the whole thing into a dedicated 
div element, which is holding the style attribute to 
shift everything at once. 



Templating Easily with Scala 



OK, now we must change the calling instruction in the index . scala . html template 
by adding the header and footer HTML, shown as follows: 



li5tContainer.5cala.html x 



2 
3 
4 
5 
6 
7 
8 
9 
10 
11 



index.scala.html 



^(message: St ring) [level : Int , list : Seg[ St ring] ) 



@main( "Welcome to the Packt Publishing' s Play 2,0 Demo") { 

\.\.\.\.\.\.\^.^ - v - v y.y.y.y.y.y.y.y.y.y.y.y.y.y.^.y.y.y.y. 

* :hl>@message</hl> 
(alistContainerl 

-= h@l e v el >Le v el @l e w el < / h@l e v el > 
K level, list) { 

-div^--- end of Level 01 evel </di«> 

} 

} 



That simple! We just created the "classic" header-body -footer layout, where the 
former and the latter are simply passed as parameters. Having a look at their type, 
Html, and how we passed them, we can see that we just wrote an HTML block 
(including the Scala one) at will. 

The following screenshot shows the result in the browser: 



<- OH O localhost:9000 



It Works! 



Level 1 

• me 

• and you? 

• tea 

• for two? 

— end of Levell 
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Using domain models 

Up until now, we played with integers and character strings; that was really cool, but 
not so representative of what we will face in the real world. Most of the time we're 
dealing with domain model instances that may represent complex object trees and 
myriad properties. 

In this section, we will create an item class that will be used in place of string in 
the list of things to be disPlayled. The following screenshot shows this (in both Scala 
and Java): 



/ Item.java X Item. scala X 


1 package models: 




: import org, joda. tine. LocalTime : 

4 

5 public class Item { 

public String user; 

public LocalTime timestamp; 

public String message; 

10 

public ItemtString user, LocalTime timestampj String message] { 

12 this . user - userj 

13 this. timestamp = timestamp; 

14 this. message = message; 

15 } 
16 

17 } 


: import org, joda, time. LocalTime 
4 

" case class It em( use r ; St ring, timest amp : LocalTimej message ; St ring) {} 



As you can see from the previous screenshot, we created the class in the models 
package; this is because we've just introduced the last component of our MVC 
pattern (the M part). As a Controller is defined in the controllers package and 
a View in the views package, a Model commonly resides in the models package. 

The same remark applies for the models package as did for the 
views one. It's no longer mandatory, but it's a rule of thumb 
^fcs^ to place models under the models package. For instance, the 
models package is imported by default in templates. 

To use it, we must perform the following steps: 

1. Change the list parameter in the listcontainer and index templates to 
use the new Item class rather than string. 

2. Adapt the index action to create items and not strings. 

What would have to be done is to modify the rendering of the list to use the data 
of item. However, we'll take this opportunity to create a dedicated template: 
listlt em. scala .html. 
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This template is meant to render an item within a list (ul), which could be achieved 
in the following way: 



1 @( it em : It em ) 

3 
4 

5 <style> 

"Li. item span { 

width: lOQpxj display : inline-block; 

8 } 

9 </ styles 
10 

11 <li class="it em" ><span>@it em . user</span> <span>[ @it em , t imest amp] <-'span > > @item , message</li> 



We added a quick and dirty styling instruction, but we'll see in the 
coming sections that LESS could be used instead. Furthermore, this 
tag being here means that it will be added for every single item, 
which is not desirable obviously. 

Now that we've seen a lot of templates, listitem.scala.html should look 
familiar. The only thing that is very new is the ©import statement, which 
should be self-explanatory. 

Let's use it in the listcontainer template: 
\~i MstContainer.scala.html 



1 @( header : Html ) (level : Irrt , items : Seq[ Item] ]( footer : Html 

2 

3 @import models. Item 

4 

5 <div sty"le="margin-le"ft : @{5*le¥el}V> 
gheader 

■ ul id="list@level "> 

8 

@items.map { item => 
@listltemi item! 

11 } 

12 

13 ul- 

@f ooter 

15 </div> 
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We simply adapted the list by renaming it items, changing its type from Seq [String] 
to Seq [item] , and finally calling the listitem template in the map body. 



[ 



Reflecting the same changes in the index template will be 
left as an exercise. However, one could just check the source 
code provided in the code files of the book. 



] 



The last thing that is needed is to modify the action to create an item sequence. The 
following screenshot shows the Scala version (the Java one is left as an exercise): 



•7 



T 



lis.tCn ntainer.5tala.html X . index, sea la. html 



Application. java 



I package controllers 

3 import play.api._ 

J impart play.api.miic,_ 

5 

6 import model s . Item 

import org . j oda .time , LocalTime 

8 

object Application extends Controller { 

10 

II def index = Action { 

val level = 1 
ual items = Seq( 



Iistltem.scala.html 



val level = 1 
ual items = Seq( 

It em( "Turgidson" . Local Time , now( ) , "Uh, ve're,,, Still trying to figure out the meaning of the las phrase, sir."), 
It em ( " Muf f ley " j Local Time. now(]j "There's nothing to figure out, General Turgidson, This man is obviously a psychotic"). 
Item! "Turgidson" , Local Time , now( ] , "We-he-ell, I'd like to hold off judgment on a thing like that, sir. until all the facts are in 

] 

0k( views.html ,indes( "It Works !") (level , items!) 

} 



Having done all of the adaptation, we can return to our browser and check what's 
going on. 



It Works! 






Level 1 






• Turgidson 

• Muffley 

• Turgidson 


[07:53:55.019] 
[07:53:55.019] 
[07:53:55.019] 


> Uh, we're... Still trying to figure out the meaning of the las phrase, sir. 

> There's nothing to figure out, General Turgidson. This man is obviously a psychotic 

> We-he-ell, I'd like to hold off judgment on a thing like that, sir, until all the facts are in. 


— end of Level 1 







Cool, huh? But we could do better, couldn't we? 



[ 



The quote shown in the previous screenshot has been extracted 
from probably one of the greatest movies ever — Dr. Strangelove or: 
How I Learned to Stop Worrying and Love the Bomb. 



] 
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Re-using our code 

In this section, we'll enjoy ourselves a bit by playing with what we have seen and 
learned so far, in order to make our application look more interesting. 

The following screenshot shows what the goal is: 

It Works! 



- Chat Thu Aug 16 17:29:11 CEST 2012 - 



- Chat #1 - 



* me [17:29:31.742] > Hello! 

• other [17:29:31.742] > HI! 

* me [17:29:31.742] > Fine? 

• other [17:29:31.742] > Yes. 



Chat #2 - 

• rue [17:19:31,74!] > Ifs hot today I 

* other [17:29:31,742] > Indeed... 



- Chat Fri Aug 17 17:29:31 CEST 2IH2 - 
- Chat #1 - 

* me [17:29:31.742] > Hello! 

• me [17:29:31.742] > Youhou? 
■ no-one [17:29:31.742] > ... 



- Chat #2 - 

• me [17:29:31,742] > Ding ding! 

• me [17:29:31,742] > Poueeeeeeeeeet? 

• no-one [172931,742] > ... 



- Chat #3 - 



♦ me [ 1 7:29:31 . 742] > No one? 

* no-one [172931.742] > Yes? 



At this stage, we're able to show a list of items with a header and a footer, which 
together would define a new structure: chat. A chat is a discussion between people 
and can occur several times in a single day. So, the following screenshot shows the 
definition of this class: 
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j Chat.java X V Ii5tltem.5cala.html X V Application.java X V I 

1 package models : 

2 

3 import org.joda.time. Dat eTime j 

4 import ] a v a . ut il . Li st .: 

5 

5 public class Chat { 

7 

public Dat eTime date; 
public int occurrence; 
public List<Item> items; 

11 

public Chat ( Dart eTime date, int occurrence, List<Itein> items) { 
13 this. date = date; 

this . occurrence = occurrence; 

15 this. items = items; 

16 } 

17 



Quite simple and obvious. But now we're going to try to use it as the top-level type of 
our application; thus the index page should render chat instances rather than item. 

For that, we'll have to change the signature of the index template to only take a list 
of Chat instances (note that we'll use j ava . util . List for convenience in the Java 
controller). Then we'll have to adapt the listcontainer template to take a single 
Chat instance; so we will have totally removed the level parameter from the scope. 

j Chat Java x Ii5tltem.scala.html x Application. jaua x \ 



16 import org. ]oda, time. Dat e I lme j 

import org.joda.time. Local Time; 
18 import org.joda.time. Days; 

19 

20 public class Application extends Controller { 

21 

22 public static Result indexf ) { 

DateTine today = Dat eTime, now( ) ; 

DateTirne yesterday = t oday. minus (Days. ONE] ; 

25 

Chat chatll - new Chat' yesterday , 1, asList ( 

new Item( " me " , Local Tine , now( ) , " Hell o ! " ) , 
new Item! " ot he r" , Local Tine , now( ) , " Hi ! " ) , 
new Iten( " me " , LocalTime , now( ) , " Fine ? " ) , 
new Iten( " ot he r" , LocalTime , now( ) j "Yes " ] 

31 ) ) \ 

32 //later on 

Chat chatl2 = new Chat ( yesterday , 1, asList ( 

new Item! " me " , LocalTime . now( ) , " It 1 s hot t oday ! " ) 
new Item! " ot he r" , LocalTime. now( ) , "Indeed ..." ) 

36 ) ) ; 

37 

Chat chat21 = new Chatftoday, 1, asList ( 

new Item( " me " , LocalTime . now( ) , " Hell o ! " ) , 
new Item( " me " , LocalTime . now' ) , i: Youhou ? " ) , 
new Iten( " no - one" , LocalTime . now( ) j ¥^™f|~ 

42 ) ) ', 

Chat chat22 - new Chatftoday, 2, asList ( 

new Iten( " me " , LocalTime . now( ) , " Ding ding ! " ) j 

new Iten( " me " , LocalTime , ncvl ] , "Poueee^-^-^-^t? I , 

new Iten( " no - one" , LocalTime . now( } , 

47 )) j 

43 

Chat chat23 = new Chatttoday, 3, asList ( 

new Item! "me", LocalTime, now( 3 , "Mo one?"), 
new Item( " no - one" , LocalTime ,now(], "Yes 7 " ) 

52 ) ) \ 

53 

retu rn ok ( index . render ( "It Works ! " , asList ( 

55 chat 23, 

56 chatll, 

57 chat 21, 

58 chatl2, 

59 chat 22 

60 )) 
) J 

52 > 
63 

54 } 
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The previous screenshot shows a very simple code example that creates a bunch of 
chat instances with underlying items. 

For such use cases, that is, initializing with test data, Play! has a special feature that 
enables a much higher level of control over the application. This feature is called a 
global object. Such an object is a singleton that will be created by Play! at startup and 
will provide plenty of hooks such as onstart and onBadRequest. This object in Scala 
or class in Java should be created keeping in mind the following points: 

• It must extend the GlobalSettings type (provide default implementations 
for all hooks) 

• It must either be declared at the root of the application with the name Global, 
or its fully qualified path must be configured in the application . conf file 
using the key application, global 

With this object created, one could override onstart in such a way that data can be 
created for testing purposes. 

Application- wide hooks take anApplication instance as parameter, I 

rJgrX which allows us to execute code whether we are in the Dev or Prod I 

^fc^" mode. Because mode is a field of the Appl icat ion controller, it can I 

have one of the following values: Dev, Prod, or Test. I 

The problem now is that the Chat instances are completely shuffled, and if we leave the 
listcontainer template as is, we'll get something similar to the following screenshot: 



It Works! 


-- Chat #3 - 

■ me [17:44:46.822] > No aaef 
♦ do-qlic [17:44:46.822] Yes? 


- Chat #1 - 






[17:44:46.822] > Hello! 
[17:44:46.822] > HI! 
[ 17:44:46.822] > Fine? 
[17:44:46.822] > Yes 


- Chat #1 - 




■ me 

■ me 


[17:44:46.822] > Hello! 
[17:44:46.822] > Youhou? 
[17:44:46.822] > ... 


- Chat #2 - 


. me [1 7:44:46.822] > Its Hot today! 
. other [17:44:46.322] > Indeed... 


-- Chat #2 -- 


. me [17:44:46.822] > Ding dlnfl! 

. me [17:44:46.322] > Poueeeeeeeeeef? 

♦ no-one 1 1 7:44:46.822] > _ 
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Which is uglyl 

To solve this, we'll use Scala at full power by using the following methods: sortBy 
and groupBy on Seq, and toSeq on Map. The following screenshot shows our new 
"empowered" template: 



1 


@( message : St ring] ( chats : List [ Chat ] ) 










3 


@import models. It em 




4 


@import j ava . ut il , List 




5 






6 


@main ( "Wei come the Padrt Publishing 's Play 2,0 Demo 


) { 


7 


<hl>@m e s s a g e -= / hl> 




8 


@chats 




9 


. so rt By (_, occurrence) 




10 


,groupBy(_,date , tcDate j 




11 


.toSeq 




12 


.sortBy(_,_l) 




13 


.map { dateAndChats => 




14 






15 


<diw class="date"> 




16 


<h2>- Chat @dateAndChats._l --</h2> 




17 


@dat eAndChat s ,_2. map { chat -> 




IB 


@listContainer{ 




19 


<h3>- - Chat #@chat . occurrence - 


</h3> 


20 


Kchat) { 




21 


<hr/> 




22 


} 




23 


} 




24 


</div> 




25 


} 




26 


} 





As we can see from the previous screenshot, we're able to use the 
methods we saw in Chapter 2, Scala - Taking the First Step, on j ava . 
util . List. That's because of some magic that implicitly converts 
List instances to Seq on the fly. But we won't cover this in the book. 

Calling this template, we get a not found : dataAndchats error. This is because 
of the formatting used to align the methods chaining after ©chats. This is a sad 
limitation of the template compiler, it needs Scala stuff to be single lined if not 
wrapped in curly braces. 

In short, the following steps explain what has been done on the chats list: 

1. We sorted all instances based on their occurrence. 

2. We grouped instances that have a similar date, resulting in a Map instance 
where the date is the key and the list of chats is the value. 

3. We converted the resulting map's items into a sequence of tuples 
(key- value pairs). 
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4. We sorted this sequence by the first element of the tuples (the date). 

5. Finally, we mapped all tuple instances to an HTML excerpt. 

A Tuple2 class in Scala has two properties, _1 and _2; these can I 
be seen as key and value when they represent a key-value pair. | 

Checking back in the browser, we'll get the result disPlayled at the start of this section. 

Funny, huh? Now, try to make exactly the same kind of sorting and grouping using 
Java; (just joking). 



Skinning with LESS pain 

This small section's intent is to show you how well Play! 2 is integrated with the Web 
stack, especially the HTML styling. 

Everyone who has worked with CSS knows that certain things are driving us 
crazy, such as the no-variable feature, the no-hierarchy feature, the vendor-specific 
boilerplates, duplication of code, and so on. 

These problems are addressed by LESS, which is a richer way of defining styling 
rules through the use of the following: 

• Mixins: These are like a predefined set of properties that can be embedded 
in other rules. A mixin can also take arguments to change the value of 
these properties. 

• Variables, which are probably the worst lack in pure CSS. 

• Functions: These are JavaScript code and can be used to change how a rule or 
a value is defined. For example, using a dedicated function one could lighten 
a color or darken it, and much more. 

• Hierarchical definitions (avoiding "repeating yourself" in selectors): Rules 
can be embedded to mimic the hierarchy of elements rather than replicating 
the selectors. 

Play! 2 will compile (by default) all LESS files that are in app/assets/stylesheets 
into CSS files that will be placed in the public/stylesheets folder. So these CSS 
files will be available just as any other styling files: using their URL; but Play! will 
also handle them using HTML features in such a way that they won't be fetched 
several times for nothing (for instance using the ETag). So, we're going to skin our 
templates a bit by creating a new file, app/assets/stylesheets/book. less. 
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Before we forget, we must add the related style import into our main template: 



1 gltitle: String) (content : Html) 

2 

3 <!DOCTYRC ttml> 
A 

5 <hrtnil 

-=:head:=- 

title gtitle title 

<link rel="stylesheet " media="screen" hret="@routes . Assets . at ( ''st^lesh^et^rnain .£ss" ) "> 

9 

<link rel= "st ylesheet " media= "screen" href="@routes . Asset s . at ( "stylesheet s/book . ess" ) "> 

11 

<link rel=" short cut icon" type="image/png" href= "^routes . Asset s . at ( "ijiia^eg^fHjtf^cajn .pjig." )" > 
■-script src="@rout es . Asset s . at ( " ^jaj*ajiiGjnyTtj5^c^i£r^ - 1 . 7. 1 . min .^s" ) " t ype="t^ext^av^scr^gt " ></ script > 
14 ^head- 
is <body> 

@content 

17 body 

18 </rrtml - 
19 



Next, I've added sample content for our application. It uses some of the features 
brought by LESS. They are very easy to use, and so are left to your interpretation. 



i 

2 
3 
4 
5 
6 
7 

8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 



@import " book - ut il s . I ess 



body { 

width: 960px; 
margin: auto; 

background-color: desaturate 1 lighten 1 @bgColor, 25'. i , 65V 1 J 

border: 2px @bgColor solid; 
.border- radius ; 

padding: Opx 15px; 



hi { 



color: saturate 1 dbaseCclor, 254) J 



.date { 
h2 { 



border: lpx black dotted; 
. border- radius* lOOpx l ; 
color: @baseColor; 



.chat 1 

.boat-sh.adovi.-2px, -3px, 2px, f adei spin' @bgColor, 15'.), 30%!) 
h3 { 

border: lpx black solid; 
, border- radius; 
color: @baseColor 

} 

li.item span { 
width: lOOpx; 
display: inline- block; 



&:first-child { 

color: lighten' 

} 



DaseColor, 15'. 



&.time { 

color: saturate 1 @baseColor, 85% i 
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The first line imports another LESS file defined in our project too. 
Everything can be found in the code files of the book. 

Summary 

Reaching this checkpoint, we've seen enough about the templates to build some 
amazing ones ourselves, with related server-side interactions— at least for static ones; 
dynamic ones will come soon. 

We've learned what exactly a template is in the Play! Framework 2 (a Scala one) — 
an HTML, XML, or TXT file that embeds Scala code. Then we saw how to add 
parameters to make type-checked functions out of them, allowing us to combine 
them into full-fledged layouts. Furthermore, we took the opportunity to apply what 
had been learned in the previous chapter, and see its worth. 

Now that we can create a UI, we have to interact with server-side businesses and 
third-party layers such as a database. That's exactly the goal of the next chapter. 




Handling Data on the 

Server Side 

In the previous chapter, we were introduced to the templating system that enables us 
to create amazing views or to render data coming from the server. 

In this chapter, we'll focus on this last point: server data. Until now, it was 
hardcoded in our actions and given directly to the views. 

Of course, it's never that simple; data is regularly coming from a database, or at least 
has been provided (at some time) by a user. So, we'll see how Play! 2 deals with these 
use cases. The following is an overview of what will be achieved in this chapter: 

• Create an HTML form to represent data 

• Send data to the server 

• Retrieve data from the server 

• Add constraints to the data 

• Persist data in a relational database 

• Provide and render back the data to the client 
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Feeding some data 

In this section, we'll cover the basis of dealing with data, both on the client side 
within HTML views and the server side by manipulating a domain model. 

Actually, Play! 2 provides helpers and commodities for these two sides and eases 
their integration, even if a wire transfer occurs in between them. 

We'll start by allowing the user of our application to provide some data, and the 
most common way to do that is by using HTML forms. Hence Play! 2 brings a 
shared concept for forms on the client and server sides. 

Forming a (server) form 

The Play! 2 data API is based on the notion of a form to declare a structure. For that, 
the framework contains a fully-fledged API that resides under the package play, 
api . libs . data, wherein we'll find the Form class. In order to learn how to use it, 
we'll see how to create a user of our application. 

We'll start with the simplest User structure ever: 

\f User^a^ 

1 package models: 

2 

public class User { 

public String name; 

5 } 

6 



Ok, for now our User class is just a wrapper around a name; of course, it will be 
enhanced further to demonstrate the power of Play! 2's data API. 

Now that the server knows what a user can be, we'll tell it how it 
can be represented from the outside (that is, strings) by creating a 
server-side form. The Java version requires less work than the Scala 
one; that's because of the Scala "youth". In Java, people have already 
tackled the trickiness of reflection, but with Scala, it's still evolving. For 
your information, Play! 2's reflection library is the Spring data binder. 
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For that, we'll create a new controller, Data, where we'll define a new form for our 
User class, which will be marked as static to allow us to use it in future actions: 



User.java 


x ^ Data.java x 




impo rt 


pLay . Libs . *; 


8 


impo rt 


models . *; 


9 


impo rt 


pi ay. data. validation.*; 


1Q 


impo rt 


static play. data, validation. Constraints. »; 


11 


impo rt 


] avax , validation , *; 


12 


impo rt 


views , html . *; 


13 


impo rt 


j ava . util . *; 


14 






15 






16 


public 


class Data extends Controller { 


17 






18 


static Fonn<User> userForm = form( User, class) ; 


19 






20 


} 





The Java data binding is so easy when the structure to be represented is a 
data container. Thanks to reflection, via the Spring data binder, what Play! 2 
has defined for us is a way to bind a user to any map of data that matches the 
User structure — that is a dictionary. 

Let's try to interact with the outside world using such a simple map. For that, 
we'll create an action, a template, and the related routing. 

The template will look like the code shown in the following screenshot: 



data.5cala.html 




1 @( use r : Use r ) 

2 @main( "Data tests" ) { 

<hl>@user . name hi 

4 } 



The routing is simply the code shown in the following screenshot: 









GET 


/data 


cont rollers , Data], test ( ) 
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And finally, the controller is shown as follows: 



16 


public class Data extends Controller { 


17 




18 


static Form<User> userForm = form( User, class) ; 


19 




20 


public static Result test() { 


21 


Map<String, String> toBind = new HashHap<St ring. String:*!): 


22 


to Bind . put ( "name" , "Siegfried" ) ; 


23 




24 


User user = userForm . bind(toBind) . get () \ 


25 




26 


return ok( data . render! user) ) ; 


27 


} 


28 




29 


} 



- For those that are reading the paperback version of this book, I'd 

% \ recommend you have a look at the source code provided in the code 
files of the book and try them, rather than decipher it on paper. 

Before executing the code, let's review it a bit. The template and the routing are fairly 
simple, so let's stick with the action only. 

The test action is doing the following tasks: 

• It creates a container of data representing the structure: a simple dictionary. 

• It adds one piece of data that is keyed by name and a dummy value. The key 
is well chosen in order to match the user's name field name. 

• It uses the bind method on the form using the data container. This will feed 
the data to the underlying binder. 

• It calls get on the resulting (filled) form to retrieve the structure expected. 

• It calls our template with the result to show what has been bound. 

The following screenshot shows the result when we go to the URL 

http : //localhost : 9000/data on our browser: 



QXi lULi 




Siegfried 





Splendid! Our User instance has been created and it contains the correct data. 
We're now able to create a user using a dictionary and ready to use the wire to 
receive our data! 
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Ingesting data 

In the coming sections, we'll focus on how we can send data to the servers that is 
complex and is constrained in its shape and type. The first step being how to deal 
with a request for content. 



Extracting the data 

Earlier we saw how to create a structure from the dictionary, which was created by 
us. However, in a web environment, such a dictionary will be coming from the client, 
for instance, the browser. 

In this section, we'll see that Play! 2 comes with everything that we might need to 
map our external view back and forth to our server-side structure (until now User). 

To illustrate the simplest case, we'll create an HTML form that will mimic 
the dictionary: 



U5er.java X V Data.java x y data.scala.html X 

Lv 




@( user : Option! User] ) 


2 


@main( "Data tests") { 


3 


@if ( user . isDef ined) { 


4 


hi -@user . get . name hi 


5 


} else { 


6 


hi Feed some data-- hi 


7 


<form method="GET" action="/data/post "> 


8 


--input type="text" name="name"/> 


9 


<input type="button" name="send" value="Feed"/> 


10 


Form =■ 


11 


} 


12 


} 



This form was created directly from the previous template by changing its signature 
from a simple User to an Option [User] . This enables us to re-use the same template 
for two different cases: 

• To show the view when the optional user is present 

• To present the form otherwise 

[ ■ An Option is a Scala structure that defines an absent or present T 
data in a type-safe way. A given value will be of the type Some, I 
whereas an absent one will be of the type None. I 



Handling Data on the Server Side 

Reviewing the form, we can note a new URL (/data/post) that will handle our 
new request for a new action (post), which we'll cover in a moment. The following 
screenshot shows its route definition: 



9 


# Data 


t est s 






10 


GET 


/data 


cont rollers 


Data .test ( ) 


11 


GET 


/data/post 


cont rollers 


Data , post ( ) 



So we have said that we want all URLs of the specified form to be routed to the post 
action in the Data controller. 

Let's see what this new action does: 

public class Data extends Controller t 

static Form<User> userForm = formi User. class) ; 

public static Result test() { 

return ok ( data . render ( Seal a Option' (( User) null)))); 

} 

public static Result post() { 

User user = userForm . bindFromRequest (). get () ; 

ret urn ok ( dat a . render ( Scala . Option 1 user) ) ) ; 

} 

} 

First of all, we see that we have used a new method on the form, bindFromRequest, 
which is meant to retrieve the data needed by the form somewhere in the request. 

Why somewhere? Actually, this method is able to look up data of several types and in 
several places. Depending on the content type, the HTTP method, and the encoding, 
this binding will look for data in: 

• The query string: This is our case, because we have sent a GET request. 

• The body: For POST/PUT methods. There are several options here because the 
content could be a map of URL parameters, a multipart, or JSON encoded. 
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In fact, the binding method will look everywhere to gather all the data and then it 
will retain the ones declared in the form definition to find which it's expecting. 

After having found everything, it returns a Form instance filled with these values on 
which we may call get in order to retrieve the related domain object. But, we could 
also call the data method that would give us back the dictionary of values. 

Having reached this point, we can now provide our brand new user to the data 
template rendered within an ok (status 200) response. 

I _ See how we used Playl's specific class, Scala, which contains a lot I 

I r^STX °f methods to interact from Java to Scala. Here we used it to create I 

I ^fes^ Scala . Option by giving it the options user (results in Some (user) ) I 

I or null (correctly cast to have None of the underlying type User). I 



Trying this in the browser, we'll get the following result: 











Feed some data 


The Duke 


|H»Dut» Feed 





That was really cool! From browser to domain object without any manual actions 
needed. I know what you are thinking, the use case is so simple that it doesn't reflect 
reality. So let's now test it a bit more by adding something new— validation of a 
complex structure. 

Enhancing your data 

In the real world, data is more complex and is required to satisfy some constraints 
for applications to accept it. In this section, we'll see how to deal with complexity and 
the next section will cover the constraints. 

As Play! 2 is made for realistic applications, it already contains everything we might 
need to handle complexity. 
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For now, a user is nothing more than a name; but a real user (as more data is 
attached), has an age, a gender, an address, some friends, and so on. 
In brief, he/ she can be represented as follows: 



User.java 



1 
2 
3 
4 
5 
6 
7 
8 
9 
1G 
11 
12 
13 



package models: 

import j ava , util 
import play, libs 



_ 



List; 

F, Option; 



public class User { 

public String name; 

public Integer age; 

public Boolean female; 

public Address address = new Addressi i 

public List<User> friends; 

public Option<User> spouse; 

} 



Address. java x 
package models; 

public class Address { 

public String fullStreet. 
public String county; 
public String country; 

} 



This should look like stuff we have already seen (possibly thousands of times). A 
significant change worth noting, however, is the public accessors on the class fields. 
This is due to the fact that Play! will generate them for us at compile time, so that 
they will be available for any other reflection-based tool. 

The interesting things are that we have added one external indirection (address) and 
two internal ones (friends and spouse). What would be really great is if we could 
bind everything from a single request! Ok, let's do some cool things now. 

The really good thing at this stage, in Java, is that we don't have to touch anything in 
the server-side form definition, thankfully, due to the binder. Having said that, we 
can infer that the needed work will be on the client side only. 

Earlier when creating our HTML form, we did it by hand mimicking the User 
structure and hardcoded the action's URL. That's not what we'd expect from a 
framework like Play! 2, and it's true because the framework brings a lot of helpers 
to generate client-side code based on server-side information. So, rather than 
adapting the existing HTML form to match the new User structure, we'll refactor 
it using Play! 2's features. 
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User.java X \ Address. Java * Data, jaw a x V data.scala.html 




jserForm : Form! User] ) g*I*.§ 
@main("Data tests") { 

@if( userForm , value . isDefined) { @*2*@ 
hi (Suse rFo rm . get . name ( @userForm . get . age ) ■■ hi §*3*g 
-=h2>Lives at (auserForm , get , address , fullSt reet ■> h2 
} else { 

hi Feed some data-- hi 
@hel per , forml action = routes , Data , post [) ) { 
@helpe r . input Text ( use rFo rm( "name " I I 

■ input t ype=" submit " name^'send" i/alue="Feed" 



There are a lot of new concepts in this form. Conveniently, the interesting lines have 
been indexed using a comment and their review is as follows: 

1. Rather than using a user (even in an option to avoid NPE) directly, we're 
now using the server-side form itself. 

2. In the previous version, we were checking that the option wasn't None. Over 
here we can do the same on the value of the form— its value is actually None 
until some data is used to fill it in, bound with valid data in an action. 

3. In the case where the form is holding a value, we've access to the get method 
of it in order to get the user back. 

4. Also, this form is where we see the first usage of the helper package 
provided by Play! 2. This one is defining plenty of utility functions (templates 
in fact) that are able to generate HTML code. In this case, we used the form 
template that generates an HTML form tag. Passing it a route, it will be able 
to set the correct action and method attributes according to what is defined in 
the routes file. 

5. Our second usage of this package is the usage of a template that generates an 
HTML input tag of type text. To generate it, it requires a form's field, which 
is retrieved by using the given form instance, using it as a function with the 
field name (userForm ( "name" ) ) . 



The routes file is compiled in objects under the routes object. Actually, 
all controllers will be available in this object, but reversed so that we're 
able to recover the mapping routes for a given pair controller-action. So in 
the template that we just discussed, it provides the form helper with the 
URL and the HTTP method defined for the post action. 

The @* *@ notation is simply comments in the Scala template's syntax. 
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So far, so good; we have changed the signature of the template that required us to 
change our action a bit. But, we'll also take the opportunity to change the HTTP 
method of the post action to something more relevant for a modification of the 
server-side state: POST. 



[ 



Not only GET and POST HTTP methods are allowed, but also all 
HTTP-standardized methods such as PUT, DELETE, OPTIONS, 
and so on. 



] 



Data.java 



Public cLass uata extends t_,ont roL Ler t 

17 

static Form<User:> userForm = form! User, class j . 

19 
20 
21 
22 
23 
24 
25 
26 
27 
28 



public static Result show!) { 

return ok(data, renderluserFormJ ) j 

} 

public static Result post!) I 

return oMdata.rendertuserForm.bindFromRequestl))); 

} 



^ routes 

1 * Routes 

# This file defines all application routes t Higher priority routes first) 
# 



# Home page 
GET / 



2 
3 
4 
5 
6 
7 
8 

9 # Data tests 

10 GET /data 

11 POST /data /post 

'S-S-S-S-S-S-S-S-S-S-fv-v-v-v-' 

12 
13 

14 # Map static resources from the /public folder to the /assets URL path 

15 GET /assets/*file cont rollers , Assets , at t path="/public" , file! 
16 



cont rollers , Application , indei( 



cont rollers , Data , show! 
cont rollers , Data , post [ 
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We can be satisfied now by how simple our actions are. The show method (renamed 
from test) is just asking the template to be rendered using the userForm instance, 
and the post one does the same but asks for a new instance of the form bound to the 
request. That's all! We can now start editing and showing our user as the output of 
our form. Let's try this: 



Feed some data 

name 

Ace 


Ace () 

Lives at 


Feed 





So, we retrieved what we had done earlier, but User is now far more complex than 
a simple name. This means it is now time to update our form with all of the relevant 
information about the new fields. 





JheLper , torm( action = rout es , Data . post () ) t 
ghelper . input Text ( use rForm ! "name" ) ) 








@helper . input ( userFo rm! "age " ) ) { (id, name, value, a^r 
<input tvpe=" number" name="@name" id="@id" @tohttm 

} 


IS 1 =s 
ArgsC args) > 


@*l*g 




@helper. checkbox! use rForm( "female ") ) 










■ f ieldset > 

-■legend - Add r e s s < 1 egend 










@hel per , input Text (user Form( " address, full St re et") , 










^helper , inputText ( 

user Form(" address, county"), 
' label - > "County" 

) 










(ahel per , sel ect ( use rForm (" address . count ry" ) , Seq( 










" " - > 11 — " , 
" AR" -> "Arda", 
"BE" -> "Belgium" , 
"SL" »> "Smurfs Land") 

j 










f ieldset : - 







Wow! A lot in a few minutes, isn't it? 

In this new version of the template, we have defined almost a whole user; what 
hasn't been done yet are the links to other users. How did we achieve that? This 
was done thanks to the default helpers available in Play! 2. 
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Some save points have been set in the template, which means that it's time to review 
them one by one: 

1. The first thing we did is create the HTML input field for the user's age, which 
is an integer (Ok, could be of a short type). For this kind of data, HTML5 
has defined a new type of input, the number one. There is no inputNumber 
template defined in Play! 2 (at the time of writing), however, it is very trivial 
to create our own using the generic input template. 

More than just using the template, we've had to create the HTML block 
by ourselves, with the help of the given data. At this stage, you might be 
wondering about the worth of this, but we'll cover that when validation occurs. 

2. Then we wanted to let the user define their gender. For that, a Boolean is 
used. So, we used the checkbox template to generate a checkbox. 

3. The easy part has been done. Now, there is the link to the address 
information, which is, itself, structured. We wrapped this part of the 
form in a dedicated f ieldset tag. 

4. In this f ieldset tag, we defined the input text for f ullStreet and county. 
It was trivial, but what is very cool is how we retrieved a form field using its 
path to the information from the user. Indeed, we can navigate the object's 
graph in the forms simply by using the dot notation. The only thing to ensure 
in this case is that every intermediate object is at least initialized to dummies 
(otherwise an NPE will be thrown). 

As the labels are ugly by default (they equal the name of the field), we used 
an argument of the input to set a custom label to something more readable. 



[ / The label is declared in the parameters list using a symbol that starts 1 
\% V with an underscore character. So a symbol is, briefly, a name (without 
value), and its syntax is similar to val but starts with a quote. 1 

5. For the last bit of data, country, we wanted to present a list to the user. 
HTML has a specific form element for this case: select. This element has a 
name and contains a list of options defined by a value and a display. 



Of course, Play! 2 enables us to define such HTML blocks really easily (which is a pain 
otherwise), all by passing a list of Tuple2 values where the first component is the value 
that will be sent with the form and the second component is the display one. 
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So now, what happens if we enter some data in the resulting form? 



Feed some data 



Bilbo Baggin 



address. fttllStteet 
| Bag End 

County 



jShire 
address.couutry 



Feed | 



Bilbo Baggins (111) 

Lives at Bag End 



Feed some data 



address-fiillSlreel 

I 

County 



addTess.country 





Lives at 



The first try was a real success, but what about the second one (on the right). A guy 
with no name, no age, and no home — the first piece of data is strange, the second 
one is frightening me, and the last one makes me sad. Let's try to take things one step 
further by adding validation. 



Validating our data 

What we're able to do now is create complex forms (both on the client and server 
sides) to represent our data, however, most of the time, they have to satisfy some 
constraints— business ones, for instance. 

Java has a Java Specification Request (JSR) defined for exactly this situation, 
JSR 303, wherein how constraints can be added to Java models— using 
annotations — is specified. 

So, Play! 2 takes advantages of this JSR and enables us to use it to validate our data, 
but it also defines custom validators that are missing in the specification. 

What we'll find very convenient is that the validation information is available on the 
browser side as well, thanks to the form HTML helpers we saw earlier. 
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Considering our User and Address models, the following screenshot shows how we 
could ask Play! 2 to validate them: 



Data.java 



x data.scala.html 



J Us 



9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 



package models; 

import ] ava . ut il . List ; 
import pi ay. libs. F. Option; 

import play . data . *; 

import pi ay. data. validation. Const raints. 
import javax, validation. Valid; 

public class User { 
@ Required 

public String name; 

@ Required 
@ Email 

public String email; 

@ Required 

(Minis) 
@Haxil50) 

public Integer age; 
@ Required 

public Boolean female; 



a Valid 
@ Required 

public Address address 
(3 Valid 

public List<User> friends; 



new Address 1 i ; 



(3 Valid 

public uption<User> spouse; 



Address. java 

package models; 



3 
4 

5 
7 
8 
9 
10 
11 
12 
13 
14 
15 
1'5 
17 
13 
19 
20 



import play . data . *; 

import pi ay. data. validation. Const raints. 

public class Address { 
@ Required 
@ Patterni 

value="[A-ZHl}\\v*, [0-9]+", 
message="A street starts with... 

) 

public String fullStreet; 
@ Required 

public String county; 

@ Required 

(IHaxLength! 2) 

public String country; 



Actually, we'll find everything we might need in the package play . api . validation, 
especially the static methods available in the Constraints class that defines the most 
common annotations. But, sometimes we might need ones from the JSR; for instance, 
in the User model we imported Valid from the j avax . validation package. Also we 
can see that while defining the constraints, a new field, email, has appeared. 
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Browsing the code, we'll find almost all of the validation instructions that have been 
set to be trivial. Let's review them one by one: 

1. We start with the required name field, which states that the field won't be 
valid if a null value is given. 

2. Then moving to the new field, email, we can see that it is also required but 
that it is also constrained to be an Email annotation, which is simply asking 
for a validation against the classic e-mail pattern. 

3. For numbers, we very often need to assume that the value will always be 
contained within a predefined range. This constraint is rather simple to 
define using the Min and Max validation rules. 

4. The next annotation that we now meet is the Val id one. This one is related 
to Required but is for embedded structures. That is, if an external object has 
to be set and is also constrained by validation rules, we can ask the system 
to check its validity as part of the upper-level object validation process (it's a 
kind of a cascade on validation request). 

5. Moving to Address, we use the Pattern validation, which supersedes the 
Email validation rule, letting us define our own pattern. That's exactly what 
has been done for the street, which is supposed to be fully qualified by 
containing the street and the number. 

6. Nevertheless, it is not the only interesting thing there; we can see for the first 
time the message property in an annotation. This message is what will be 
returned if this particular validation fails. 

7. Now we can jump to the last one, validating the country information. We 
should remember that our form was showing an HTML select element 
with options having their values set to two chars (IDs). So these IDs will 
now be validated by the MaxLength constraint. 
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This last rule might not be enough though, because someone could send a custom 
HTTP request with a fake country ID. To validate that the value is one of the 
predefined options, we can define our own logic in a dedicated method — validate: 







//LUblUM : : sample implementation ot Hard coded data 




public enum Country { 




ARDA[ "Arda" , "AR"J, 




BELGIUM! "Belgium" , "BE"), 




SMURFS_LAND( "Smurfs Land" , "SL"J; 




public String name; 




public String id 




private Count ry( String name, String id) 1 




this. name = name; 




t his .id = id ; 




T. 
J 




public static Country get By Id ( String id) { 




for [Country c: values! J") i 




if (c.id.equals(id)) { 




return c; 




} 




} 




throw new III egal Argument Except ion 1 "Count ry not found => Bad id 

} 

} 


{"+id+"}") ; 


tg Required 




@Patterni 




value="[ A-ZHl}\\v«, [Q-9]+", 




message="A street starts with an upper case, and ends with a number 


after a comma" 


) 

public String fullStreet; 




H Required 




public String county; 




g Required 




gMaxLengthl 2) 




public String country; 




//CUSTOM : : validation rules 




public String validate!) { 




try { 




Country, getByldl count ry) ; 




return null; 




} catch [ 111 egal Argument Except ion e) { 




return "Bad country : " +country; 




} 




} 




} 
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As shown in the previous screenshot, the validate method is checking our custom 
rule and will return null if it succeeds; an error message otherwise. 

It seems that we've protected a lot of things on the server side now, but how are they 
presented (if they are) on the other side — in the HTML form? 



Feed some data 



Required 



Minimum value; 
Required 

Maximum value: 150 
gender 

■ 

Required 

- A d d ress 

address. fullS treet 



County' 



ad dress. country 



Feed some data 



Required 



Minimum value: 
Required 

Maximum value: 150 
gender 

Required 

-Address 

add ress. tullStreel 



address.countrv 



Gosh! Without changing anything on the client side, the validation instructions have 
appeared on each field. Recalling what we wondered earlier, "What was the value of 
such helpers?" So, here we are; and it's not the end. 

- You're right; the address' constraints aren't shown in the \ 

\2k/V dedicated fieldset, nevertheless, this has been fixed in the 2.1 I 
version of Play!. I 



On the right side (previous screenshot) is presented a slightly skinned version of our 
HTML form in order to highlight where to look. 
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Ok, but how is it supposed to work when incorrect data is sent to the server? 



he form has Terrors 



Feed some data 



This field is required 
Required 



Must be greater or equal to 
Minimum value: 
Required 

Maximum vaiue: 1 50 



gender 

J 

This field is required 
Required 

i—Address 



address. fuIIStreet 

^ue de la bie&ira^e 

A street starts w ith an upper case, and ends w ith a number after a comma 

Gountv 

I 

This field is required 

address. counrrv 

I- ' 'I 
This field is required 



Feed 



Impressive, isn't it? Without changing a single line of code in our templates, every 
error just shows up. The only thing that has been done is to add a CSS rule to display 
the error messages in red. 
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Oh yeah! The red div element is also a little addition. This addition takes the number 
of errors that are available in the form object directly, which is shown as follows: 



@if ( use rFo rm , hasErrors) { 

*.div st v1.e="background-col or : red ; color iwhitej " : -The form has @use rFo rm , e r ro rs , size errors div 

1^ } 



Moreover, it's intuitive! 

Persisting them 

At this stage, we have learned the functionalities offered by Play! 2 to represent our 
data on both sides (server and client). However, that data was all transient. Indeed, 
the HTML form was submitting data to an action that rendered them directly. 

In a web application, most data isn't transient, but persistent — data is the value of 
modern applications (moreover, social-oriented ones). 

If we remember the structure of our User model, it includes two references to other 
users: one optional (spouse) and one multiple (friends). Such data must come from 
somewhere other than the User form, because the actual form is only defined for a 
single user. 

This implies a third piece in our architecture, a database, in order to retrieve 
previously created data— User. Once we have that, we'll adapt the User form 
to present to the client's user a way to set this extra information. 

Activating a database 

Most of the time, within web applications, the chosen database is a relational one. This 
use case is so common that Play! 2 integrates perfectly with a dev/ test in-memory 
relational database: H2. Of course, in production, we'll be able to target any database 
server that we would like to use. 

In order to ask Play! 2 to start such an in-memory database server, all we have 
to do is enable it in the configuration file. In fact, the settings are already in our 
application, conf file but commented out. 
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So, in this file, locate the following lines and uncomment the db . default . driver 
and db . driver . url properties: 



20 


# 


Database configuration 


21 


# 




22 


# 


You can declare as many datasources as you vant . 


23 


# 


By convention, the default djt^sjouj^ce is named default" 


24 


# 




25 


# 


db. default .drive r=org.h2. Driver 

\AAAAAAAAAAAAAAAA> Wv 

db . default . url = "] dbc : h2: mem : play" 


26 


# 


27 


# 


db . default . usej^sa 


28 


# 


db . default . password= 


29 


# 




3G 


# 


You can expose this datasource via JNDI if needed (Useful for JPAi 


31 


# 


db . default . ] ndiName=Def aultDS 



These lines are defining an in-memory HSQLDB (as the URL is telling us), targeting 
a database named play. The other settings, credentials, won't be useful for now (but 
they will be in production). 

The very last setting is for helping us expose our data source as a JNDI name, which, 
as said in the comment, is very useful when using JPA (or other libraries requiring 
such JNDI stuff). 

Something to note in this configuration is the form of the properties; they all start 
with db . default, which means that we're defining the default JDBC data source. 
Obviously, if we need several data sources, we can simply duplicate the block and 
use a different qualifier than default. 

Ok, we enable the database, which will now start when we launch the server in 
dev mode (play run), but then, what can we do with it? That's the purpose of 
the next section. 

Accessing the database 

Having enabled a database server, loaded the related driver, and so on, we can use 
the tools provided in the play . db package. This package contains everything we 
might need to interact with the database, that is, all JDBC-related facilities. We will 
now discuss how we might deal with JDBC, HSQL, Play! 2, and a browser. 
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We start with a class that is able to interact with the underlying database — creating a 
table, inserting data, and getting it out. 



SarnpleDb.java X T JDBC.java X routes x jdbc.5cala.html 

:■. 

1 package db.jdbc: 

2 

3 import play.db.*; 

4 

5 import ] ava , sql . *; 

6 

7 import j ava , util , List ; 

3 import j ava , util , ArrayList ; 

9 

10 public class SampleDb { 
11 

public static Connection connect!) { 

13 return DB, getConnection! ] ; 

14 } 

15 

public static void disconnect ( Connection connection) throws Exception { 
connection. closef ) j 

18 } 

19 

public static void createTest Table! ) throws Exception { 
Connection c = connect!); 

22 try { 

c , createStatement (). executeUpdatel "create table test(value va rcha r [ 50) ) " ) ; 
24 } finally { 

disconnect ( c ) ; 

26 } 

27 } 

28 

public static void insert Test Data! String v) throws Exception { 
Connection c = connect ( ) ; 

31 try { 

32 //OK OK => prepared statement . . , SQL injection bljhblah . . . 

33 // » Just for testing purpose here '''' 

c , createStatement (). executeUpdate! "insert into test values ('"+«+"')"); 
35 } finally { 

disconnect ( c ) ; 

37 } 

38 } 

39 

public static Lisrt:<St ring> getTestData! ) throws Exception { 
Connection c = connect C ) j 

42 try { 

ResultSet resultSet = c . createStatement ( ). esecuteOuery! "select * from test"! 
Lisrt:<St ring> values = new Arrayl_ist<St rings! ) ; 

while ( resultSet , next () ) { 

values, add (result Set .getStringll)); 

47 } 

48 return values; 

49 } finally { 

disconnect ( c ) ; 

51 } 



This class contains methods that are able to connect to a database using a db 
singleton provided by Play! 2. This singleton is performing all of the necessary 
tasks for us when accessing a database, that is, it retrieves the connection string, 
the credentials (if any), and so on to create the connection. 
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Doing so, we are connected to the default data source (db . getDatasource is also 
available for other data sources). 



[ 



A good exercise is to think about how this code would have 
been written in Scala, with the help of currying and sequences. 



] 



The implementations are purely JDBC ones, nothing very interesting in there, but 
we'll see in the next section how we could do the same with an ORM such as Ebean. 

Now that we can deal with our database, the following screenshot shows a controller 
that will enable this code to be used in the frontend: 



SampleDb. java 



X Y JDBC. java 

/ 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 



package cunt rollers : 

import play.*; 

import play.mvc.*; 

import static play. mvc. Results. *; 

import play, libs,*; 

import ] ava . util . List ; 

import db , j dbc , SampleDb; 

public class JDBC extends Controller { 

public static Result page() { 

return ok( views .html .jdbc. render ( ) ) ; 

} 

public static Result tablet) { 
try { 

SampleDb. createTest Table! ) ; 
return ok( "table created"); 
} catch (Exception ej { 

return internal ServerError(e. get Message! ) ) ; 

} 

} 

public static Result test (String value) { 
try { 

SampleDb. insertTestData( value) ; 
List<String> vs = SampleDb. get Test Data( ) ; 
return ok( Json.toJsonf vs) ) ; 
} catch (Exception ej { 

return internal ServerErrorfe. get Message! ) ) ; 

J 

} 
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It's trivial, but it does the job. This controller allows the outside world to create a 
table (showcase only), to insert data, and return them all... in JSON. However, we 
should pay attention to the test action that involves a string parameter: value. 

The very first action is simply asking a dedicated template to be rendered: 



jdbc.5cala.html X 






1 

2 
3 


ill 

@main( "jjdbc test") { 







4 


^script > 






5 


11 JavaScript that makes AJAX call using the "href~ in the 


J, t_ 


D 


// and toggles the 


Lis one after another 




7 


$ ( function 1 i { q 






30 


}| ! 






31 


</script> 






32 


<style> 






33 


ol li { 






34 


displ ay : none ; 






35 


list -style : none; 






36 


} 






37 


ol li : first -child { 






38 


display : block; 






39 


> 






40 


</sty\e> 






41 


<ol id=" j dbc result "> 






42 


<li><a href="@routes 


. JDBC. table" >Create t ahl e </ a></l i> 




43 


<li><a href="@routes 


. JDBC.test ( "Don ' 't insert me" ) ">f irst 


val </ax/li> 


44 


-=li><a href="@routes 


. JDBC. test ( "What did I said?" ] ">second 


val </a></li> 


45 


-=:li><a href="@routes 


. JDBC.test "Grrr" ] ">third ?al </a»</li> 




46 


<li>End</li> 






47 


</ol> 






48 


<ul id=" result "> 






49 


</ul> 






50 


} 







This template is meant to be self-sufficient and dynamic; that's why JavaScript code 
was necessary to call actions dynamically, retrieving either a string or a JSON to be 
shown in a dedicated result list (at the bottom). 

But what is interesting here is what the HTML links are referring. Indeed, routes, 
and the last three are using variables to create the correct URLs — of course, test 
takes a parameter! 
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Now we still have to create those routing instructions, and the following screenshot 
shows them: 





# TEMP 


for tests 






18 


GET 


/test/page 


cont rollers 


JDBC. page 


19 


GET 


/tjejt^/cjreate 


cent rollers 


JDBC. table 


20 


GET 


/test/Tvalue 


cont rollers 


JDBC . t est ( val ue : St ring ) 


21 











Ok, great routes, but again, let's focus on the test one to assert that it does exactly 
what we expect. It defines that a GET request on /test/message will call the test 
action with message as argument. 

See the following screenshot for this sample JDBC interaction in action: 



I! = II H I 



J 




jdbc test 

Ct ft : U localhost:9000/test/pac . <£j| 



Create tabic 



Second value 
• Don't insert me 



jdbc test 

C ft , Lj loca!host:9000/test/page 




Third value 

• Don't insert me 

• What did 1 sav? 




jdbc test 

O ft i D Iocalho5fc9000/test/page 



find 



• Don't insert me 

• What did I say? 

• Girr 



We can create full JDBC applications, but what if we would like to use an ORM in 
order to create many more boilerplates for us? This is what we're about to look at in 
the next section, that is, using Ebean with Play! 2. 
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Object-relational mapping 

Play! 2 supports out of the box an object-relational mapping (ORM), Ebean, which 
will fill the gap between our domain model and the relational database. Like any 
other ORM, it aims to facilitate the usage of a model when dealing with relational 
databases by implementing common helpers or operations such as finders based on 
the model's properties or CRUD methods. But also, such an ORM is helpful when 
propagating a transaction or to lazy load data transparently. These tools have gained 
quite a lot of attention lately, but it's still a matter of taste whether to like or hate them. 



I want to cool down Hibernate lovers that were about to see how 
Play! 2 integrates with Ebean. Definitively, the intent of Play! 2 is 
not to restrict us to their officially supported third-party libraries. So 
you'll be able to use Hibernate (or whatever ORM) you're used to 
coding with. Furthermore, Play! 2 has good support for JPA, which 
will ease your environment setup. 

As this is a book about Play! 2, it won't cover these options. 
However, the Play! 2 documentation will help with this, and 
you might want to explore these options further by going to 
http : //localhost : 9000/@documentation/JavaJPA. 

How this integration begins is simply by enabling Ebean in the configuration file: 



38 # Ebean configuration 

39 # 



40 # You can declare as many Ebean servers as you want. 

41 # By convention, the def autT^server is named "default 

42 # 

43 ebean. def ault= " model s .* " 



Fairly simple; this line (that was commented) is enabling us to define our domain 
classes under the models package to be Ebean entities. 

And, as mentioned in the comment, this single line will create an Ebean server and 
all related configurations, providing us with all we need to work with this ORM; in 
this case, it will target our default data source. 

So far, so good; we can now make the necessary modifications to our model for 
Ebean, recognizing them correctly. Like many other ORMs, this will pollute your 
source code with meta instructions — annotations, hopefully. Ebean uses the 
standardized ones from javax. persistence. 

Thus, in order to have Ebean discovering instances of User to be persisted, we must 
add two things: the first is noting that the class has to be considered an entity, and 
the second is setting an id field. 
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In Chapter 1, Getting Started with Play! Framework 2, we saw how 
to add a dependency. There we chose the Guava one; as we won't 
use it, I'd recommend removing it from the Build . scala file. 
Otherwise, it may lead to errors, due to conflicts with Ebean's 
dependencies. 





import j avax . persistence . *; 


11 




12 


@Errtity 


13 


public class User { 


14 


'5 Required 


15 


public String name; 


16 




17 


@ Required 


18 


Email 


19 


@Id 


20 


public String email; 



As mentioned earlier, new annotations were added and they came from the standard 
persistence package. 

Now, what if we hit refresh on our web page? 









Database 'default' needs evolution! 




An SQL script will be run on your database - ^^^^^^^^^^M 


This SQL script must be ru n : 


1 


#— Rev:LUps-cl9cOIO 


2 


create table user ( 


3 


email varchar(2 5 5 y not nuLL 


4 


name varchar(255). 


5 


age integer. 


6 


gender boolean. 




constraint pk_user primary key (email)) 


8 




9 




10 


create sequence user_seq; 
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Huh! Merlin was around? 

Yes, some magic happened, and it's the combination of the Ebean DDL generation 
and the Playl's evolution plugin. In short— but it would be worth it for advanced 
usage to check the documentation for both— the former is generating the relational 
database DDL for us, based on the added instructions, and the latter is detecting that 
changes are needed. How does that work? Let's break it down: 

1. Ebean detects the DDL changes needed. 

2. Play! asks it to generate it. 

3. Ebean generates it. 

4. Play! intercepts the DDL and stores it in an evolutions folder: 
/conf /evolutions/def ault/1 . sql 

5. The evolution plugin detects that an evolution file has been applied (based 
on the file number which corresponds to a version) and hooks the Play! 2 
startup to render the error page. 

6. We, as the users, click on the Apply this script now! button. 

7. Play! 2 plays the SQL script on the database. 

Looking into the created file, we'll discover that a basic structure is created based on 
properties, but not the external references such as the address or other users: 



L.sql 



1 # --- Created by Ebean DDL 

2 # To stop Ebean DDL generation, remove this comment and start using Evolutions 

3 

4 # --- !Ups 
5 

6 create table user ( 

email varchar 255) not null, 

name varchari 255) , 

age integer, 
female boolean, 
address_internal_id bigint, 
constraint pk_user primary key (email)) 

13 ; 
14 

15 create sequence user_seq; 

16 
17 

18 # --- ! Downs 
19 

20 SET REFERENTI AL_I NTEGRITY FALSE; 

21 

22 drop table if exists user; 

23 

24 SET REFERENTI AL_I NTEGRITY TRUE; 

25 

26 drop sequence if exists user_seq; 
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It is not hard to get that the plugin will enable us to write a 2 . sql file, and so on in 
order to have incremental DB schema changes. What is trivial also is that we'll have a 
different folder by data source— here the folder is named default. 

Having said that, we now have to update the Address class to be an entity, but 
something more will be needed for this class. Indeed, as it doesn't have any primary 
key, we'll have to create an internal id field, shown as follows: 



V Userjava X 


IV Address. java x 


1 


package models; 




package models: 


2 
3 


import ] ava . util . List ; 


3 


import play. data.*; 


4 

5 


import play .libs . F. Option; 


4 


import play . dat a . validation . Const raints . *; 




import play. data.*; 




import ] avax . pe rsist ence .* ; 


7 


import pi ay . dat a . val idat ion . Const raint s . * ; 






8 


import ] avax . val idat ion . Val id ; 


8 


^Entity 


9 




9T 


public class Address 1 


10 


import ] avax . pe rsist ence , *; 


10 




11 




11 


(Id 


12 


@Errtity 


12 


( Gene raft edVal ue 


13 


public class User 1 


13 


public Long internalld; 


14 


@ Required 


14 




15 


public String name; 


15 


//CUSTOM : : Sample implementation of Hard Coded data 


16 




16»- 


public enum Country tQ 


17 


@ Required 


36 


} 


18 


@ Email 


37 




19 


Md 


33 




20 


public String email; 


39 




21 




40 


( Required 


22 


@ Required 


41 T 


(Pattern! 


23 


amnio) 


42 


value="[A-Z]{l}\\v*. [0-9]+", 


24 


(IHaxi 1501 


43 


message="A street starts vith an upper case., ..." 


25 


public Integer age; 


44 




26 




45 


public String fullStreet; 


27 


@ Required 


46 




28 


public Boolean female; 


47 


(Required 


29 




48 


public String county; 


30 


3 Val id 


49 




31 


@ Required 


50 


(Required 


32 


^HanyToOne 1 cascade=CascadeType . ALL) 




(HaxLengthi 2! 


33 


public Address address = new Address!); 




public String country; 



As we can see from the previous screenshot, it's not the only thing to do; 
to link User with Address, we also need the address field of User to be added 
with a new persistence instruction, ©ManyToOne, because addresses can be shared 
across several users. 

This will result in a new DDL (to be applied on refresh), which will contain the new 
address table and a new relation (foreign key) from a new property (address_ 
internal_id) in the user table to the address table's primary key. 



[106] 
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We have to use this functionality carefully because it has caveats on production. The 
most important one is probably that such generation is not done incrementally, and 
so it will generate the whole DDL at once. However, Play! 2 has evolutions to carry 
out the incremental adaptations. 

A safe way to use it would be to generate the DDL on a test database and then create 
the incremental files manually. 

Storing and fetching - a simple story 

Reaching this section, we have created our domain model; we have also configured 
our system and the model classes to be mapped with an ORM— Ebean. In the end, we 
have a server that is able to connect to a database with tables created for our entities. 

In this section, we'll see how to use this ORM to persist and retrieve our model 
instances to and from the database. 

As we're building a web application, we'll use a controller to ask the frontend user 
what to create and what to retrieve. This controller will be our Data one, which we'll 
adapt and enhance for more advanced usage. 

So, back to our Data controller; we can recall that we only had one way to create 
an in-memory User and to show some of its information. What must be done 
now is the following: 

• Add a persist instruction to the current action to save the newly created user 

• Ensure that the address is saved and is not inserted several times with the 
same values 

• Add a new action to retrieve all created users in our database 

As we can imagine, we'll need to query the database to retrieve either all users, 
but we will also need to fetch a potential address based on its properties. 

Again, Play! 2 and its perfect integration with Ebean will help us. Indeed, Ebean 
defines Query that not only enables us to query the database using our model and 
hierarchy, but also its internal structure. However, we won't have to manage it by 
ourselves, because Play! 2 will do it for us through a Finder wrapper class. 
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Also, the Play! 2 integration with Ebean will avoid a lot of boilerplate for CRUD 
operations, because such methods will be automatically added to our model. This is 
simply done by updating our model classes to extend play . db . ebean . Model. That's 
all folks! 

As this book is not about Ebean, we won't go deeply into its 
features or arguing why it's so good. If you rely on the Play!'s team 
choices blindly, I'd recommend you go to the Ebean documentation 
(http : / /www. avaj e . org/ ebean/documentation . html) 
and check out the Model implementation too (which is almost a 
delegation to Ebean classes). Actually, using it is very straightforward 
thanks to what has just been discussed. 



Data.java X V User.java x Address, java 

\_ J. 



import static piay.mvc Kesuits 

:" import play . data . *; 

7 import play, libs,*; 

S import models, *; 

9 import play . data . validation . *; 

import static play. data, validation Const raints 

11 import ] avax . validation , *; 

12 import views.html.*; 

13 import java.util,*; 
14 

15 

16 public class Data extends Controller { 

17 

static Form<User> userForm = form( User. class) ; 

19 

public static Result shovC ) { 

21 return okC dat a . rende r( use rForm ) ) ; 

22 } 
23 

Splay db. ebean. Transactional /*1*/ 
public static Result post!) { 

Form<User> boundForm = userForm . bindFromRequest ( ) ; 
if ( boundForm . hasErrors( ) ) { 

ret urn badRequestCdata, renderCboundForm) ) j 
29 } else { 

User user = boundFo rm . get ( ) : 

Address eiistingOne = /*2*/ 
Address. find 
.vherel ) 

.eq( "fullStreefj user, address, fullStreet) 
.eq( "county", user. address. county) 
.eq( " count ry " , user. address. count ry) 
, f indUnique ( ) ; 

if (existingOne != null) ■[ f*3*f 
user. address = exist ingOne ; 

40 } 

41 user.savel); /*4*/ 
return ok(data. render( boundForm) ) ; 

43 > 

44 > 
45 

public static Result allUsersU { 

47 //necessary in order to fetch the vhole address at once for each user 

48 //Otherwise it vill be proxied and its field won't be available in the templates. 
List<User> users = UserTTiridT] oin( "address" ), findList () ; /*5*/ 

50 return ok( 

views . html. users. render(users) /*6*/ 

52 ); 

53 } 

54 > 
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Some checkpoints have been dropped into the code to let us review the additions 
easily. Let's review them one by one now: 

1. The very first thing we can see is that we have flagged the post action to be 
Transactional; this wouldn't have been mandatory if we didn't have to 
interact several times with the database (which is checking the address and 
then saving the user with or without a new address). 

2. Then we enter the wild indeed, we're using what has been added to Address 
and User and we have access to it via Model, that is; a Finder wrapper class. 
This is shown in the following screenshot (in Address): 



Data.java X User.java X Y Address. jai/a 

1 package models; 

2 

3 import play . data , *; 

4 import play . data , validation . Const raints . *; 
5 

6 import j avax , persistence . *; 

7 

8 @Entity 

9 public class Address extends play . db . ebean . Model { 

10 

11 /* 
12 

13 */ 

14 | 

public static Finde r<Long, Address> find = new Finde r<Long, Address>i 
Long, class. Address. class 

17 ); 
13 } 



3. We created play . db . ebean . Model . Finder that enables us to work on 
address' store easily, providing access to querying, update, and so on. 
In this first usage, we queried all addresses where all three properties 
match the ones from the user's address. As we expect such a combination 
to be unique, we called f indUnique on the resulted query. 

The result of such a unique query is an instance of Address (the given type to 
find) or null if none has been found. In the former case, we've updated the 
user's address to use the existing one. 

4. Now that the user is referring to a valid, unique address, we can use 
another method provided by extending Model: save. This will save the 
user but will also save all other resources related to it, in this case, Address 
(because of the cascade strategy). The address will be created if it wasn't 
found earlier (based on internal id this time), or it may be updated. And, 
at the very end, the user is created. 
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5. We also added a new action, allUsers, which retrieves all users from the 
database. But it does it differently than expected (all ( ) is also available in 
Model), because of the lazy loading of the address field. 

That's true. Yes, Ebean is also handling the lazy loading for us, but if we 
want to show all users at once, with their address in a template, we must ask 
Ebean to preload them while fetching the users — so a join is performed on 
the address field. 

6. The view part is left as an exercise, but an example is provided in the code 
files of the book. 

Porting to Scala 

Until now, in this chapter, we have talked about the Java API that Play! 2 provides to 
deal with data, nevertheless there is also a Scala version. We'll have a quick overview 
here by implementing the same workflow (validation, forms, persistence). 

Actually, both APIs look the same, but in Scala, binding is very often our job, 
whereas in Java, it was the job of the reflection-based tools — Scala doesn't have 
many tools like that, but times are changing with its 2.1 release. 

The first impact regarding this is that, in Scala, binding form instances is our 
responsibility. Then there is the communication with the database, where in Java, 
we had the Model class helping us to deal with the Ebean ORM. On the other hand, 
the Scala database API takes a completely different direction called Anorm— which 
stands for Anorm is Not an Object Relational Mapper— because it relies on SQL 
rather than automatic mapping. 

To start with, we'll need to activate the database plugin; this is done in exactly the 
same way as in the Java version. So we're already prepared to step into the model 
classes definition. 
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Models 

As we'll need the same classes as in the Java version of this example, we'll create a 
User class and an Address class. For now, we'll tackle the User class only, as the 
Address class will be very similar. So, the following screenshot shows what the 
User class looks like: 



f 

W User.5cala X T Data.scala 


X 




1 


package models 






2 


import play . api . Play . current 






3 


import play . api . db . DB 




//l 


4 

5 


import anorm._ 




m 


6 


case class User( 






7 


name : St ring. 






8 


email : Pk[ St ring] = Not Assigned, 




//a 


9 


age : Int , 






10 


gender : Boolean, 






11 


address : Address, 




//4 


12 


spouse : Option! User]=None, 






13 


f riends : Seq[ User]=Seq( ) 






14 


) { 







Pretty trivial. User defines its structure (containing a special type for its email field) 
and then it imports the DB API to create connections and transactions. 

For the search and persistence tasks, we can see (in the next screenshot) the first 
usage of Anorm, which is a relational database access layer that supersedes JDBC by 
providing a better API— less verbose, binding back and forth with the domain model 
using Scala features such as pattern matching, for instance. 



15 


def save = 




16 


DB.withTransaction { implicit conn => 


//5 


17 


email .toOption . map { e => User.load(e) } match { 


//6 


18 


case None => create 




19 


case => update 




20 


} 




21 


} 
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In this save method, we can see that a choice will be made over creating or updating 
the data in the database. The following screenshot shows how create can be defined: 





def create = DB.withConnection { implicit conn => 


in 


24 




SOU 


//B 


25 









26 




INSERT INTO user( 




27 




name , 




28 




email , 




29 




age , 




30 




gender, 




31 




address internal id 




32 




) 




33 




VALUES ( 




34 




{name} , 




35 




{email}, 




36 




{age}, 




37 




{gender}. 




38 




{add ressld} 




39 




) 




40 








41 




) .onl 


us 


42 




' name -> name, 




43 




'email -s email . get , 




44 




' age -> age, 




45 




' gender -> gender, 




46 




'addressld -> address . internalld . get 




47 




) . executeUpdate( ) 


/no 


48 




this 




49 


} 






50 








51 


def update = DB.withConnection { implicit conn =>E3 




71 


} 








} 







As a lot of new things were introduced so fast, the best idea would be to review them 
one by one: 

1. We import the db API from Play! 2; it will provide us with the ability to wrap 
database accesses within a transaction or at least give us a connection to a 
data store. 

2. The next import is the anorm package, which allows us to use a specific type 
such as Pk and especially the sql case class. 

3. The Pk type is helpful to define primary keys and is similar to Option; 
having said that, it can either be NotAssigned or id (x) —very helpful when 
generated primary keys are used. 

4. User keeps a heavy reference to Address, as it's not an Option type; we can 
imagine that it will be eagerly fetched with the user. 
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5. The save method on User is able to determine if the user already exists 
(based on the email value) and then asks whether to create it or update it. So, 
checks and persists are done in a single transaction— which are implemented 
as the body of the withTransaction function that ensures a transaction is 
present from the start of its body until its end where a commit takes place. 

6. This point is twofold; we see that Pk can be used as a classic Option and 
then we call a function of its companion (a companion of a class can be used 
to create static functions) that is able to search on its potential value (for 
illustrative purposes only because email will always be of the id type) — this 
search will be covered in the next section. 

7. Still in the same transaction, we can now retrieve the underlying connection 
to the database to create the user in the database. For that, we can simply ask 
for this connection using the withConnection function that will execute its 
body in a classic JDBC connection. 

8. The SQL case class is providing us with a way to create our custom SQL 
queries — it's a kind of wrapper around string and JDBC prepared statements. 

9. So it allows us to replace placeholders and set it directly to the underlying 

PreparedStatement. 

10. Add also to execute the query (insert in our case). 

By the way, we can see that Anorm is not an ORM (hence its name), so it cannot 
really see the structure of the data that it will have to handle. Because of this, it is 
not able to generate the DDL for us — that's a drawback of such a choice, but in favor 
of a lot of other advantages that are beyond the scope of this book. Thus we, as 
developers, are responsible for creating and maintaining the DDL ourselves. 

[rljTX For this example, we can simply copy the 1 . sql file from the 
Java project as the same structure has been defined. 

Parsing the DB result 

With Anorm, we're able to retrieve data from a database in several ways. Now we'll 
see the parser one; nevertheless, it is worth checking its documentation for further 
help on this topic (http : //localhost : 9000/@documentation/ScalaAnorm). 
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In this section, we'll see how we can retrieve data from the database as domain 
model instances by defining a mapping in the form of a SQL parser (manual ORM). 



Use 

w 


.scala x V Data.scala x Address. scala x 


74 


ob] ect User { 


88 


object Address { 


75 


import anorm. Sq~L Parse r . 


89 


import anorm, Sql Parser ,_ 


76 




90 




77 


/** 


91 


/** 


7E 


* Parse a User from a Result Set 


92 


* Parse an Address from a ResultSet 


79 


*/ 


93 


*/ 


80 


vaT withAddress = { //l 


94 


val simple - { 


81 


get [Pk[ St ring] ] ( "user . email "J - J/2 


95 


get [ Pk[ Long] ]( "address. internal id") - 


82 


get[String](" user. name") - 


96 


get [ St ring] ( "address . full street") - 


83 


get [ Irrt ]( "user. age") - 


97 


get [ St ring] ( "address . county" ) - 


34 


get [ Boolean] ("user, gender") - 


98 


get [ St ring] ( "address . count ry "1 map { 


85 


Address . simple nap { 


99 


case internalld-fullStreet -county-country => 


85 


case etnail -name~age-gender~address => //4 


100 


Address[internalld. fullStreet, county, country) 


87 


User(name, email, age, gender, address) 


101 


> 


88 


> 


102 


> 


89 


} 


103 




9G 




104 


def load( addressld : Long) : Optionl Address] - 


91 


def load( email : St ring) : Option! User] = 


105 


DB.withConnection { implicit conn => 


92 


DB.withConnection i implicit corn => 


106 


SQL[ 


93 


5QL( " " " 


107 


SELECT 


94 


SELECT 


108 




95 


* 


109 


FROM 


96 


FROM 


110 


address 


97 


user, 


111 


WHERE 


98 


address 


112 


internal id = {addressld} 


99 


WHERE 


113 


"""1 ,on( 


100 


user . address_int ernal_id - address . internal_id 


114 


'addressld ->■ addressld 


101 


AND user. email - {email} 


115 


) . as( Address . simple. singleOpt ) 


102 


) .on( 


116 


) 


103 


'email -> email 


117 




104 


1 .as(User . vit hAddress . singleOpt ) //5 


118 


def all :Seq| Address] = 


105 


} 


119 


DB.withConnection { implicit conn => 


106 




120 


SQL[ 


107 


def all : SeqtUser] - 


121 


SELECT 


108 


DB.withConnection { implicit conn -> 


122 




109 


son 


123 


FROM 


110 


SELECT 


124 


address 


111 


* 


125 


) . as( Address . simple *] 


112 


FROM 


126 


> 


113 


user. 


127 




114 


address 


128 




115 


WHERE 


129 


} 


116 


user . address_int ernal_id = address . internal_id 






117 


) . as( User .withAddress *) 






118 


} 






119 








120 


} 







Both the User and the Address companions have been shown in the previous 
screenshot in order to have the picture at one glance. 

The key points are the functions of Sql Parser, which are meant to build an SQL 
parser (of course), that's what is being done in the withAddress and simple values. 
Indeed, SqlParser defines the structure to be taken over a database's result set. This 
enables us to combine at will, but also to define several for a single model depending 
on the amount of data retrieved or to create joins for external resources such as the 
user's address. 

The syntax can help us build very complex stuff and has the advantage of being 
oversimple. For instance, in our two-level fetching for User, we combined SQL 
parsers of type string, Int, or Boolean with another one of type Address, which is 
defined in the Address companion. 
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The composition of such parsers is done using the ~ operator. Such compositions' 
results will then be mapped using pattern matching and retrieved as combined 
values to be used to create a user. 



get [String] ("column") will create an SQL parser that j 

\ parses the current row in the result set for a column named 
^* column and returns it as a String value. I 

That was all about parsing (recall that it is only one of the several techniques that 
Anorm is able to apply on a result set). Hence we've now defined the mapping 
between the relational world and the domain model one. 

Looking at the load and all functions, we'll see that it will be used in the as method 
of SQL, which is simply executing the SQL and the mapping. 

• The mapping is not usable as is when calling the database. At this J 

stage, we must also tell, for instance, if we expect zero or one row 
i^"^ (singleOpt), a single result (single) or several (*). J 



Speaking with the browser 

This last section will quickly cover how to deal with server-side forms. 

As we said earlier, Scala doesn't have great introspection libraries in the current 
version, so Play! 2 overcame this problem by providing a very neat and intuitive 
API to define a mapping between the outside world and the server-side one. 



However, we're lucky because Scala 2.10 has unleashed the power of 
macros. Given that Play! 2.1 is using this Scala version, some work 
has been done towards using macros to generate the formatting 
boilerplates. But this is only available for the JSON formatting use 
case, not yet for forms. 



This API is in the play . api . data package and notice especially the Forms object 
that defines plenty of mapping functions, satisfying almost all common use cases 
such as String, Option, Seq, embedded structures, constraints (Email, Min, Max), 
and so on. 



Handling Data on the Server Side 



In the Scala world, we create mappings by defining the structure we expect to 
come from or to be rendered to the outside world, and then we attach a constructor 
(apply) and extractor (unapply) to it. Let's see that in action: 



User.scala it y Data. scala 



package controllers 

I 2 

import play. api. _ 

4 import play . api , PI ay , cur rent 
import play . api , mvc ,_ 

5 import play . api , data , Forms , _ 

import play . api , data , validat ion , Const raints ._ 

8 

9 import play . api . db . DB 
10 import anorm,_ 
11 

12 import play . api , data ,_ 

13 

14 import models. _ 
I 15 

I 16 object Data extends Controller { 
17 

def opt ToPk[T] [ om : Mapping! Option[T] ] ) = 

om.transform[Pk[T]][o => o.maplx=^Id[s3}. get Or Else ( Mot Assigned ) , (_: Pk[T] ) , t oOpt ion) 

20 

lazy val use rMapping : Mapping [ User] =| 
mapping( 

"name" -> nonEmptyText, 
24 "email" -> optToPk ( opt ional C email 3 ) , 

"age" - > number( min=0j max=l!5Q) } 
"gender" -> boolean., 
"address" -> addressMapping, 
28 "spouse" -> ignored ( None : Option! User] ) - 

"friends" -> ignoredf SeqC ) : Seq[ User] ) 
)( User , apply) ( User , unapply) 

31 

lazy val addressMapping =| 
mapping [ 

"internal Id" -> optToPk( optional ClongNumber] ) , 

35 "fullStreet" -> 

36 [ 

text verifying pattern( | A-HI , *, I B-9] , Tj 

error="St reet starts with upper case and ends with comma and number") 

39 ) , 

"county" -> nonEmptyText , 
41 "country" -> nonEmptyText 

) (Address . appl y ) ( Add ress . unapply ) 

43 

val userForm = Form[ User] ( userMapping) 

J iC 



Not much to say; a mapping is defined as a map between outside-world keys and 
server-side representation (globally, a type plus some constraints). Furthermore, all 
functions are self descriptive, thanks to a well designed API: a DSL. 

Having defined the structure, we see that we end by passing two functions, which 
are the "so-called" apply constructor and the unapply extractor. Because we used 
case classes, these functions are automatically created and maintained by the 
compiler itself. 
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And then the rest, like the form usage and so on, is 90 percent the same as in Java 
(because the syntaxes differ). So we can mimic the actions from there. 



At the end of this chapter, we are now able to create HTML forms that are 
based on server-side structures. We learned which forms will be used to send 
data to the server, and where they'll be automatically mapped to on the domain 
model definition. 

We also learned how to manage the domain model into a database and how to 
create, fetch, or update them. 

With these forms and a database, we can now easily create a discussion between 
the server and the client using forms on both side and persistence layers to save 
the work. 

In the next chapter, however, we'll add another dimension to our model, which is the 
format of the data and their representations. Until now, we've only dealt with HTML 
or textual data. Now it's time to see how data could be represented in a different 
fashion or how to use binary data. 




Actually, functions to be passed to a form definition are just 
conversions between the values from a request and an object 
from the database (for instance). 



Summary 




Dealing with Content 

A web application always has, at some point, the need to deal with multiple types 
of content. Common content types include JSON, XML, HTML, but there could also 
be images or even videos to be stored and streamed. Play! 2 provides a clean way of 
dealing with such content types with the help of body parsers. 

We won't cover the implementation details of such body parsers, because it's 
purely based on a functional concept, Iteratee, and thus their implementations 
are in Scala only. However, we'll see how they are used and how we can gain 
benefits from them. 

In this chapter, we'll update and clean up a bit of what we have been doing so far 
in order to enable several workflows. So we will only be using examples we have 
learned up to now. The following is what will be achieved: 

• Make the Chat and Item classes persistent using Ebean 

• Create a link between an item and a user (a user's reply in a chat) 

• Introduce a new type, image, that will be part of a chat as an attachment 

• Enable a user to connect 

• Browse all chat instances 

• Allow the connected user to reply in a chat 

• Allow the connected user to attach an image to a chat 

• Show examples of UIs 

• Create an action that outputs a requested image 

• Create an action that provides an Atom feed of all chats which have specific 
users getting involved (kind of like following) 
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• In order to keep the chapter short and to the point, we'll only | 

see the Java part. Keep in mind that the Scala version is little 
different for this level of detail. 1 



Body parsing for better reactivity 

As noted earlier, the way to manage content in Play! 2 is to use instances of body 
parsers. In brief, a body parser is a component that is responsible for parsing the 
body of an HTTP request as a stream to be converted into a predefined structure. 
This has a common sense ring to it, however their strength is in their way of 
consuming the stream— in a reactive fashion. 

Reactivity, in this context, is meant to describe a process where an application won't 
block on a task that is actually idle. As a stream consumption task is idle when no 
bytes are incoming, a body parser should behave the same. It will read and construct 
an internal representation of the incoming bytes. But it can also decide at any time 
that it has read enough to terminate and return the representation. On the other 
hand, if no more bytes are coming into the stream, it can relax its thread in favor of 
another request; it pauses its work until new bytes are received. 

Thinking about an HTTP request that is sending a bunch of XML content, the 
underlying action can use the XML-related body parser to handle it correctly (read 
reactively); that is, by parsing it and providing a DOM representation. 

To understand what a body parser actually is, we'll first look at how they are 

used — in the actions. An action in Play! 2 represents the piece of software that is able 

to handle an HTTP request; therefore, they are the right place to use a body parser. 

In the Java API, an action is allowed to be annotated with the of annotation available 
in the BodyParser class. This annotation declares the expected type of request routed 
to it, and it requires a parameter that is the class of the parser that will be instantiated 
to parse the incoming request's body. 
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The following screenshot shows an example: 



import org ,w3c. dom . *; 

public class Content extends Controller { 

@ Body Pa rse r . Of 1 Body Pa rse r Xml. class) 
public static Result content!) { 

Document doc = request (). body (). asXml ( ) 

//DEAL WITH DOCUMENT 

return ok( 
//. . . 

) ; 

I 



Isn't this helpful? We've gone from a request to a W3C document, in a 
single line. Functionally speaking, this works because an action is semantically a 
higher-order function that takes a body parser and generates a function that takes a 
request (and so its body) and results in an HTTP response (result). This result will 
then be used to construct the HTTP response by Play! 2. 

In Java, it is not all that obvious how to create a higher-order function. A good way, 
however, to achieve this was to add an annotation. An annotation can be processed 
at runtime in order to execute the right body parser (in this case). 

To illustrate this, we'll have a quick look at the Scala version: 



|object Content extends Controller 


{ 


def content = Action! parse . xml ) 
val doc = request . body 


{ implicit request => 


//DEAL WITH DOCUMENT 




OKI/*. . .*/) 




} 

} 





With this Scala version, it is easy to see that an action is dealing with a function from 
a request to a response. 
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There are a plenty of predefined body parsers that can be used to handle our 
requests, and they are all defined in the BodyParser class as static inner classes. One 
can have a specific behavior to be applied on its expected request body, and even 
though a body parser has to be implemented in Scala, a Java coder can simply extend 
these current implementations. Actually, they're already providing enough control to 
cover all custom use cases. 

So, we have in our hands tools to handle the following content types: 

• JSON 

• XML 

• URL form encoded 

• Multipart (for uploading files) 

• Text 

• Raw (fallback) 

As we can see from the previous list, there is, obviously, an implementation for the 
x-www-f orm-urlencoded content type. Indeed, this is the parser we've used so far 
to retrieve data from the client side. For example, using POST requests throughout 
HTML forms. 

But wait, we never had to add such annotations to our actions, and, moreover, 
we've never looked in the parsed result. That's true, Play! 2, as a great framework, 
is already doing a lot of stuff for us. And that's because it's a web framework; it takes 
advantage of HTTP; in this case, using the content-type header. 

Based on this hint, it seems obvious that Play! Framework 2 will look in this header 
to find the right parser to apply. So annotations are mandatory, but where did we 
use them previously? In the bindFromRequest method, of course. Let's see how. 

In the previous chapter we have used form instances, and we fed them some 
data through the client. Those instances were applied on the request using the 
bindFromRequest method, and this method's job was to look for data according to 
the provided content type. And, of course, this content type was set in the header by 
the HTML forms themselves. 
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Indeed, an HTTP GET will send data in the request URL (query string), where an 
HTTP POST will be sent with a body that contains all data encoded by default as 
URL parameters (that is, x-www-url-encoded). 

So, we can now give an overview of what the bindFromRequest method does. 
When we ask a form to be filled in with data, this method will: 

• Gather data as URL-form encoded data, if any 

• Gather data from parts (if the content type is multipart-data) 

• Gather data as JSON-encoded, if any 

• Gather data from the query string (that's why GET requests were working 
as well) 

• Fill in the form's data with all of them (and validate) 

You might be wondering the worth of such annotations; the quick answer to that is 
they allow new types of parsers, but they can also enforce certain actions' requests to 
match a given content type. 

Another advantage of such annotations is that they allow us to extend or narrow the 
length of the body that can be handled. By default, 100 K are accepted, and this can 
be either configured (parsers . text .maxLength=42K) or passed as an argument to 
the annotation. 

With all of this in mind, we are now ready to implement these concepts in our code, 
and what we're going to do is to update our code base to create a kind of forum. 
A forum where one can log in, initiate a chat, reply to non-closed ones (based on 
their date), or even attach files to them. 

Creating a forum 

In this section, we'll refactor our existing application in order to enable it to act as a 
forum. And, chances are high that it won't be necessary to learn anything new; we'll 
just re-use the skills gathered so far; but we'll also use the parsing commodities that 
Play! 2 offers us. 
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Reorganizing and logging in 

The very first thing we have to do is to enable a user to log in; this ability was already 
created in the Data controller. However, for that, we'll update our Application 
controller a bit, to create a new index action that will check whether a user is logged 
in or not. 



Content.java X | Chats.java X 7 Application.ja X 






21 


public class Application extends Controller { 


22 




23 


public static Result index ( ) { 


24 


String email = session! ) . get ( "email " ) ; 


25 


if (email != null) { 


26 


return redirect! routes. Chats . all Chat s ( ) ); 


27 


> else { 


28 


return unauthorized! 


29 


views .html .login, render! ) 


30 


li 


31 


} 


32 


} 







So, index is now the new entry point of the application and can be routed from / 
in the routes file. And, it's solely meant to check if a user has logged in or not. This 
check is based on the session content, as we simply check whether a user's e-mail is 
present in the session. 

We never see what a session can be in Play! 2, but we saw that 
Play! 2 is completely stateless. So, a session in Play! 2 is only an 
encrypted map of the value stored in the cookie. Thus it cannot 
be that big, and definitely cannot contain full data. 

If the user is present, we redirect the request to the chatroom by calling redirect 
with the expected action. This will prevent the browser from posting the request 
again if the user reloads the page. This method is called POST-redirect-GET. 

Otherwise, we respond with an Unauthorized HTTP response (401) that contains the 
HTML login page. 
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The two actions (shown in the next screenshot) are so simple that we won't cover 
them further, except for a single line: session ( ) . clear ( ) . It is simply revoking the 
cookie's content, which will require the subsequent request to create a new one, 
which then doesn't contain the previously stored e-mail. 



34 


public static Result "Login! ) { 


35 


return ok( 


36 


views .html .login, render! ) 


37 


1: 


38 


} 


39 
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public static Result logout!) { 


41 


session! I , clear) 1 j 


42 


return ok( 


43 


views .html .login, render! ) 


44 


1; 


45 


> 



And finally, enter, which shows how a request's body can easily be handled using 
the relevant method: asFormUrlEncoded. It should look like that shown in the 
following screenshot: 



47 


public static Result enter! ) { 


48 


Hap<St ring. String! ]> pa rams; 


49 


papains = request (). body! ). asFormUrlEncoded! ) ; 


5G 




51 


String email = pa rams . get (" email ")[ 0] ; 


52 


User user = User . find . byld ( email ) ; 


53 


if (user = null) { 


54 


return redirect! routes. Application . 1 ogin ( ) ); 


55 


} else { 


56 


session! "email " , email); 


57 


return redirect! routes. Chats. allChats! ) ); 


58 


} 


59 


} 


6G 




61 





Indeed, one would normally have to use a form to retrieve this information for us, 
which would do it for us (behind the scenes); but in this case we have only a single 
parameter to retrieve, so a form would be overkill. 

So far, so good; we are now able to create a user, log in with it, and use a login page. 
To target having cleaner code, it would be worth splitting the Data controller code into 
several pieces (matter of a good separation of subject). Hence, the Users controller is 
created, in which will be placed the user-related actions taken out of Data. 

Now, we'll move back to something we saw earlier but didn't cover — the routes . 
Chats . allChats ( ) action call. 
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Chatting 

In the previous section, we were introduced to the Chats controller and its alichats 
action. If the names are self-descriptive, the underlying code isn't that much. 

First of all, we're now dealing with chat instances that must be persisted somewhere 
in a database, along with their underlying items. 

But we'll also prepare for the next section, which relates to multipart data 
(for instance, it's helpful for file upload). That's why we'll add a brand new 
type, Image, which is also linked to Chat. 

Having said that, it would be worth checking our new chat implementation: 



12 @Entity 

13 public class Chat extends pi ay . db . ebean , Model { 

14 

@Id 

8 Gene rat edVal ue 

public Long internalld; 

18 

M Required 

public String topic; 

21 

a Required 

public Local Date date; 

24 

@ Required 

public int occurrence; 

27 

td Valid 

SOneToHany cascade=CascadeType. ALL) 
@OrderBy ( ''timestamg " j 

(3 JoinColuim name="CHAT_ID" , ref erencedColumnName="internal_id" ) 
public List<rtem> items; 

33 

@ Valid 

SOneToHany cascade=CascadeType. ALL] 

QJoinColumn' name="CHAT_ID" , ref erericedColumriName="internal_id" ) 
public List<Image> images; 

38 

39 public Chat ( ) { 

4G } 

41 

public Chat i Local Date date, int occurrence. List litems- items. List<Iniage> images) t 
this. date = date; 

this . occurrence = occurrence; 
this. items = items; 

this. images = images; 

47 } 
48 

public static Finder<Long, Chat> find = new Finder-cLong, Chat>' 
Long, class. Chat , class 

51 ); 
52 

public static int cccurrencesFort Local Date date) { 

return f ind . whe re ( " dat e = : date" ), setParameterl "date" , date) . f indRowCount ( ) ; 

55 } 
56 

: } 
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Thanks to the previous chapter, there's nothing all that new here, except the Image 
type itself. Before we cover the item and image types, we'll first go to the Chats 
controller to see what's going on. 



Content.java X Chats. java x"^^^"lBiage,java x ^ ~' Chat.java 



16 

public class Chats extends Controller { 

static public Forni<Chat> chat Form = f o rm ( Chat . cl ass ) ; 

19 

public static Result loadChatO { 

Hap<St ring, String! ]> queryString = request (). querySt ring( ) ; 
Long chatld = Long, pa rsel_ong( query St ring . get ( "dhatid" )[ G] ) ; 

23 

Chat chat = Chat. find 

.where! ) 

. eq( "internalld" , chatld) 
. ] oin( "items" ) 

. j oin( "items . user" ) 
. ] oin( "images" ) 

. ] oin( "images . user" ) 
31 , f indUnique( ) ; 

32 

return ok( 

views . html . chat room . render( chat , itemForm, imageForm) 

35 )j 

36 } 

37 

public static Result all Chats I I { 
return ok( 

views . html . chats . renderi Chat . find . all ( ) ) 

41 ) ; 

42 } 



Finally, we can see our all Chats action; it's simply rendering all existing instances 
within a template. Even the rest of the controller is simple; everything is done in 
templates, which are left as exercises (we're so good at them now!). 

However, there's still the loadchat action that contains something related to 
this chapter: 

Long chatld = Long . parseLong (queryString . get ( "chat id" ) [0] ) ; 

This action handles requests asking to show a particular chat instance, which is 
a resource and thus should be served using a GET request. This implies that the 
parameter value is stored in the query string (or in the URL itself) rather than in the 
request body. 

Regarding query string access, it's more interesting to analyze the following line: 

Map<String, String [] > queryString = request (). queryString () ; 
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In fact, all actions contextually refer to a request object, which is accessible using 
the request ( ) method. This request object declares a querystring ( ) method that 
returns a map of string and an array of strings. What comes next is trivial; we just get 
chatid out of this map (ok... in a very unsafe way). 

Until now, we have been able to log in and access the chatroom, where we can create 
or show chat instances. But we're still unable to reply to a chat. That's what will be 
tackled now. 

For that, we need to create an action that will, based on a chat ID, post a new 
message linked to the logged in user, and then attach this message as an item of the 
underlying chat instance. 

For this, we must update the item class with persistence information. Afterwards, 
we'll be able to update the chats controller in order to create instances. 



package models; 

2 

3 import o rg ,j oda . t ime , Local Time ; 

4 

5 import play. data.*; 

6 import play . data . validation . Const raints . *; 

7 import j avas . validation . Valid; 

8 

9 import j avax . persistence . *; 

10 

11 @Entity 

12 public class Item extends pi ay . db . ebean . Model { 

did 

@ Gene rart ed Val ue 

public Long internalld; 

16 

HneTnlne 

public User user; 

19 

@ Required 

public LocalTime timestamp; 

22 

@ Required 
IgHaxLength' 140) 
public String message; 

26 

public Item( ) { 

23 

29 } 

3Q 

public Item(User user, LocalTime timestamp, String message) { 
this. user = user; 
t his . t imest amp = timestamp; 
this . message = message; 

35 } 

36 

37 } 
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Ok, it's like a beefed-up POJO; let's jump into the action that will create item instances. 

The workflow to post a message for a user starts by enabling him/her to participate 
in a chat. This is done by loading it (using the loadchat action) where the user will 
be able to post a new message (an overview of the UI will be presented at the end of 
this chapter for illustration only). 

The following screenshot shows how it can be done: 



Content.java X y Chats.java # V Image. java X v Chat.java X V Item.java X 

IE. J \ . * 

public class Chats extends Controller { 



static public Form<Chat> chatForm = form( Chat . class) ; 

19 

public static Result registerChat ( ) { q 

26 } 
27 

public static Result loadChatf) { q 

44 } 
45 

public static Result all Chat s() 

50 } 
51 

public static Result createChatU { 

63 } 
64 

static public Form<Iteni> itemForm = form( Item, class) ; 
public static Result talk (Long chat Id) \ 

User user = User. find . byld( session! "email ")) ; 
Chat chat = Chat. find 

■where! ) 

. eq( "internalld" ; chatld) 
71 . ] oin( "items" ) 

|.findUnique( ) ; 

73 

Form<Item> boundForm = itemForm . bindFromRequest () ; 
Item item = itemForm . bindFromRequest (), get () ; 
item . user = user; 
chat . items . add( item) ; 

78 

chat . save( ) ; 

80 

81 return ok( 

views . html . chat room , render! chat , itemForm, imageForm) 

83 ) ; 

84 } 



Observe how the user was recovered using the session. 

Still, nothing cumbersome to review here, we've just re-used a lot of stuff we've 
already covered. The action receives a POST request in which information about the 
message is given, and then we can bind the request to itemForm and finally save to 
the database the item contained in the resulting form. 
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At most, we should notice that we're still free to encode the body as we want, and 
also that the chat ID is not a part of the form but a part of the action signature— that's 
because it is a part of the URL (routing). 

We've almost finished our forum; the only thing needed is to enable users to 
post images. 

Handling multipart content types 

The HTTP protocol is ready to accept, from a client, a lot of data and/ or large 
chunks of data, at once. A way to achieve this is to use a specific encoding type: 
multipart/form-data. Such requests will have a body that can hold several data 
pieces formatted differently and attributed with different names. So, Play! 2 is a web 
framework that fits into HTTP as much as possible; that's why it deals with such 
requests goods, and provides an API that hides almost all of the tricky parts. 

In this section, we'll see how one could upload an image along with some caption 
text that will be attached to a specific chat. 

Before diving into the workflow, let's first create the holding structure: image. 



@Errtity 

public class Image extends Model { 

public static enum ImageType { 
GIF( " image /gif" ) , 
PNG " image/png " , 
JPEG "image/] peg" ; 

} 

@Id @ Gene rated Value st rat eg if = Gene rat ionType , AUTO) 
public Long internalld; 

(dHaxLength 140) 
public String caption; 

//memoization of pic 
@ Transient 
public File pic; 

public String filePath; 

(tjOneToOne 

public User user; 

public static Finder<Long, Imago find = 

new Finder<Long, Image>( Long. class, Image. class) ; 

public Image( ) O 

public File pic() { 

//... 
} 
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This newly introduced type is not hard to understand as well; only two things 
should be pointed out: 

• The pic ( ) method that relies on the f ilePath field to recover the file itself. It 
uses a File instance to memorize subsequent calls. 

• The enum type that prepares the action logic to filter the incoming files based 
on the given MIME type. 



[ 



This logic could also be defined in the validate method. 



] 



These instances are always locked in with the connected user who uploaded it and 
will be added to a Chat instance. This will allow a chatroom to display all attached 
images with their caption beside the messages themselves. 

Now we're ready to look at the file upload itself by paying some attention to the last 
action of the Chats controller, that is, receivelmage. 



87 
88 
89 
90 
91 
92 
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94 
95 
96 
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99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
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110 
111 
112 
113 
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115 
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117 
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public static Form<Image> imageForm = formC Image. class) ; 
public static Result receivelmage ( Long chat Id) { 
User user = User. find . byld( session( "email ")) ; 
Chat chat = Chat, find 

,where( ) 

. eqC "internalld" , chatld) 
, ] oin{ "items" ) 
. f indllnique ( ) j 

I [-jET SOME DATA FROM THEN URL FORM ENCODED DATA 
Form<Image> filledForm = imageForm . bindFromRequest () : 
if ( filledForm , hasErrors[ ) ) { 
return badRequest( 

filled Form.errorsC ) .toSt ring( ) 

) j 

} else { 

Http HultipartForiiiData body; 

(77~pEC0VER THE WHOLE BODY AS MULTIPART 

body = request U.bodyC). asMultipartFormData( ) ; 

□HE PLAY2 API PROVIDES A WAY TO GET THE FILE 
+» SO EASILY ! ! ! 
Http HultipartForiiiData FilePart pic = body . get Fil e ( "p^ic ") ; 
| [77~l aHECK THE IMAGE TYPE IS VALID -- part of the enum 
it'! Image ImageType. get [ pic , getContentTypef ) ) == n uTTT { 
return badRequestC 

views , html , chat room . render( chat , itemFcrnij imageForm) 

] j 



Image image - filledForm , get I ] : 

image. pic = pic . get Fil e ( ) j 

image . file Path = pic . getFile( ) , get Pat h( ) \ 

image . user = userj 

chat . images. add(image) ; 

chat . saue( ) \ 

return ok( 

views , html , chat room . render( chat , itemFormj imageForm) 
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As we are used to simplifying the code (Play! 2 is there to ease our work, after all) 
and to get straight to the point, we reflected this in our receiveimage action.. 

In a very few lines, we declared a new action that expects requests to be multipart 
encoded containing at least two parts, where the first is a map of data (no matter 
how this map is encoded) to fill in imageForm (essentially a caption). The second will 
be the image part. 

After binding the request with the form and verifying that no errors have occurred, 
we can move to the body content in order to recover the binary data that was sent 
along with its metadata: the file content, its content type, its length, and so on. 

That was quite an intuitive thing to do - asking the body to be parsed as a 
multipart/ multidata and and get it as an Http . MultipartFormData object, which 
has a getFile method that returns an Http .MultipartFormData . FilePart value. 
To understand why we didn't specify a body parser, recall that Play! 2 is able, most of 
the time, to discover which method fits best by itself. The Http . MultipartFormData . 
FilePart type is not only allowing us to recover the content as a file, but also its key in 
the multipart body, its filename header, and (especially) its content type. 

Having all of these things in hand, we are now able to check the content-type 
validity against the image's enum, and to store the image by getting the file path of 
the provided file. 



Et voilal We have now learned about some of the features that can provide a very 
simple forum. The following screenshot shows what it could look like (without any 
efforts on the design, of course). First, the forms to show and enter archived and 
active chats: 




This file path will target the Temp directory of your machine. In 
the real world, the file should be relocated in a dedicated folder or 
maybe on an S3 repository. 



Connected as me@home.org 



Archives 



Yestatlay Chat on 2012-09-16 t | | stiow 



Active 



Chat about Today on 2012-09-1 9 T Load 



Create a new one 
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On entering an active chat, let's say the one 
the one shown next: 


named Today, we reach a page similar to 


f~" nnTipptpfl ii* mpf/jjlinmp nt*o 




Chat about Today 




So far... 


Attached Images 


• [16:13:00.257] rae@liorae.org> Which day is if? 

• [16:15:13,120] iio@one.biz > Today... 

• [1 6: 1 5:2S.O40] ine@liome.org> Ah... r'u sure? 




React 


Attach an image 


message 


caption 

1 


| 

Maximum length: 140 
Required 

| send] 


Maximum length; 140 

pic 

Choose File No file chosen 

Send 


Using the Attach an image form, we can select an image on our filesystem to be sent 
to the server. The result obtained is shown as follows: 


Connected as no@one.biz 




Chat about Today 




So far... 


Attached Images 


■ [16:13:00.257] me@home.org > Which day is it? 

• [16:15:13.120] no@one.biz > Today... 

* [16:15:28.040] me@home.org > Ah... r'u sure? 


. Yes ! I AM : 


React 


Attach an image 


message 


caption 

f 1 


! 

Maximum length: 140 
Required 

[ send | 


Maximum length: 140 

pic 

| Browse... J 

Send 
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Until now, we have spoken about handling various content types coming from the 
outside world, but what about our application having to render content other than 
HTML? That's what we're about to see next. 

Rendering contents 

In this section, we'll see how a Play! 2 server is able to render different resources in 
different ways rather than simply providing HTML pages. 

The actions' body in Play! 2 not only have the responsibility of creating resources to 
be provided to the outside world, but also of declaring how this resource has to be 
rendered. Fortunately, there are a lot of boilerplates already written for our use in the 
default actions builder. 

The so-called actions builder are the methods we have used almost blindly until now; 
that is to say, the static methods available in the play . mvc . Results . j ava class such 
as ok, redirect, badRequest, and unauthorized. 

Indeed, these methods have been overloaded several times in order to accept several 
representations. The following are some examples: 

• Content: This takes content that is of the base type of classic string 
representations such as Html, Xml, and Txt. This is also the result-type 
of a rendered template. 

• string: This will be rendered as is, as a plain text content (an overloaded 
version of the method accepts the encoding as a second argument). 

• JsonNode: This is trivial. If we create an instance of such a class, we'll have 
our resource serialized as application/ j son. 

• inputstream: This is a convenient way to dump a stream into a response 
body (accepts chunks for an HTTP-chunked encoded connection). 

• File: This helps us avoid typing new FilelnputStream (...) in 
inputstream. This accepts the file and will deal with the stream for us. 

Knowing all this, we'll now enhance our forum a bit to not only show the persisted 
attached images but also to provide a dynamic Atom feed for all chats that users 
have participated in. 

[r%P( The previous screenshot shows our attached image 
>fcj>^ being displayed. 
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To tackle this, we'll retrieve the empty Content controller we saw at the beginning of 
this chapter. And we'll add two actions, routed as shown in the following screenshot: 



28 # Content 

GET /chat/images/:imageld cont rollers, Content, get Image(imageld: Long) 

■■y-y-y-.-\---y-y-y-y-y-y-y-.-\---.--y-y-y-.-\" 

GET /content /at om/+emails cont rollers , Content , atomi, emails : St ring 

31 



The former action asks for a specific image content, whereas the latter one is asking 
for an Atom feed for certain users. 



Imaging all of the chat 

So, it's now time to render our images back to the client and show them in their 
respective chatrooms. The following screenshot shows how to do it: 

public class Content extends Controller { 

public static Result getlmagef Long imageld) { 
Image image = Image. find . byld( imageld) j 
try { 

return ok (new FilelnputStreaim image , pic( ))) ; 
} catch ( FileNatFoundException f) { 

return badRequest ( " Bad File,,,"); 

} 

> 



So trivial... take the ID, get the related image in the database, ask for its underlying 
file, and return it in an OK (HTTP 200) response. 

Thus, we're now able to use this action in our HTML templates using a simple img 
tag that has its src attribute pointing to our new action, shown as follows: 

<div sty"le="margin-left :51Qpxj "> 
<h2>Attached Images: / h2> 

@chat . images . map { i => 

li(3i. caption : -img s r :="@rout es . Cont ent . get Imaget i . int ernalld I " alt="@i . caption" i it I e= "@i . caption" /x/li> 

> 

ul 

■ div 



With the image rendering done, let's now move to the Atom feed. 
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Atomizing the chats 

This section is dedicated to the production of XML content. 

In Java, we all know how painful it is to generate a DOM structure that has to be 
dumped as a string. Actually, Scala has a native syntax for XML, but it's still better 
(easier) to use templates for that. 

Indeed, we used Scala templates for generating Html responses (remember Html 
derives from Content), but we could also generate Xml contents for the templates that 
are accordingly named. In other words, where myBeautif ulContent . scala . html 
creates an Html response, myStructuredContent . scala . xml generates Xml content. 

But first of all, we'll have to gather the data before applying them to an XML 
template. This is done in the code shown in the following screenshot: 





public static Result atom! String use rEmail 5 ) { 


33 


Hap<User, Set<Chat» chats = new HashHap<User, Set<Chat»( ) ; 


34 








35 


List<String> emails = 


lew ArrayList<String>( ) ; 


3G 


for (String e : use rEmail 5 . split ("/" J ) { 


37 






emails . add( e) ; 






38 






} 






39 












40 






List<User> users = 


User. find 


41 










. j oin( "address" ) 


42 










.where! ) 


43 










. in( "email " , emails) 


44 






.findl_ist( ) j 


45 








46 


List<Chat> list Of Chats 


= Chat, find 


47 






. fetch( "items" ) 


43 






. fetchi "items . user" ) 


49 










.where! ) 


50 










. in! "items , user , email " , emails) 


51 










.order By! "it ems, user. email") 


52 










. findList! 1 ; 


53 












54 






for (Chat chat : listOfChats) { 


55 


for litem i : chat , items) { 


56 


Set<Chat> list 


= chats . get ( i . user) ; 


57 


if (list == null] 


{ 


58 


list = new HashSet<Chat>! ) ; 


59 


chats , put ( i . 


use r 


. list); 


60 






} 






61 






list .add! chat) 






62 






> 






63 






} 






64 






return ok( views .xml. content, at om.renderlchats, users) 1 . as! "applicat ion/at om+xml " ) ; 


65 






J 
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Apart from database interactions to retrieve user and chat information, the points 
worth noting are the following: 

• We used an ok result builder that relies on a template to generate content 

• We don't let the XML's default content type to be returned (text /xml), but 
we override it by specifying the Atom one, application/atom+xml, using 
the as method on the ok response 

Having prepared the data and the content type to be rendered, we can now look at 
the real representation: the template. 

According to the action that uses the views . xml . content . atom . render method, 
the template must be located in the content package under the views one and 
must be named atom . scala . xml. And its content might be as shown in the 
following screenshot: 



atom.5cala.Kml • V Content java X 



@( chats: Map! User, Sell Chat]], users : List [ User] )|<?jcnil version="l , 0" encoding= " ut f - 8" ?> 

2 ^import org .jjoda .time . DateTime , now 

3 <feed i«Tn5=Mrttp : //ww.w3, org/2005/ At om"> 

<tit ie>Chat St ream</tit le> 
5 <updated>@now-= / updated* 
<author> 

<naae>NDDQt sab</naae> 
</ flirt ho r:> 

<id>@routes . Content . atom! users , map{_, email} . mkSt ring! "/" ) ) . url</id> 

10 @chats,map { case (u. chatListJ => 

11 @chatl_ist .toSeq . sortBy(_, occurrence) , map { c => 

12 -sentry 

13 <id>@ 

14 { 

15 routes , Content , atom! users 

16 , map{_, email} 

17 , ink St ring! "/" ) 

18 ) , absol ut eURL( request () J 

19 }/ent ry/@u , email/flc . date/fic . occurrence 

20 = xd 

■rtitle&Chat for @u . email @@ @c,date [ @c . occurrence] </titte> 

updated @c . date<- updated 
<summary 

24 @c,items 

25 , sortBy! .timestamp .toDateTimeToday .toDateJ 
,map(i =>i , user . email + " : " + i. message) 

, mkSt ring! "-=:br/>" ) 
28 </sumniary> 
</errtry> 

30 } 

31 } 

32 </feed> 

33 




We were able to gracefully generate our xml content using XML directly, which 
avoided the headaches with DOM manipulations. 



Dealing with Content 



The only noticeable thing in the previous screenshot is the first line (all of the 
others are just data manipulations for displaying purposes), which is declaring the 
necessary parameters directly after we find the first XML line. That's because of the 
XML specification that requires this meta-information to be positioned at the very 
first character. 



With this small amount of effort and code, we're already done and can now see the 
result in an appropriate Atom viewer, shown as follows: 



G fi localhost:9C » "\ 1 






Chat Stream Subscribe with: PffifjlSgBff^Ml | 






Chat for me@home.org @ 2012-09-20 [1] 


me@home.org : Ih 
no@one.biz : Hi 
me@home.org : Huh 


Thj Sep 20 2012 02:00:00 


Chat for no@one.biz @ 2012-09-20 [1] 


me@home.org : Ih 
no@one.biz : Hi 
me@home.org : Huh 


Thj Sep 20 2012 02:00:00 



This client enables us to add our feed to Google Reader for instance. 
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Summary 

We're at the halfway point of the book and we've already built a forum-like web 
application with really basic features, but we are able to at least create chatrooms for 
particular topics, join them, participate with messages, or add images to them. All 
this without any pain or boilerplate, thanks to the content management features that 
Play! Framework 2 puts in our hands for free. 

Indeed, in this chapter we were able to deal with complex routing involving several 
ways to provide information, using different HTTP methods and URLs with or 
without extra parameters. Such requests were used to feed the server with data very 
easily, by using a single API that is independent of how the data is represented. For 
instance, on both sides we were dealing with forms. 

Body parsing was there to help us, and to facilitate resource binding with our 
constrained forms. Moreover, they are consuming data in such a way that even 
large data sets won't crash the server —they are consumed reactively. 

At this stage, we're also able to send data to the client in whatever fashion we'd like. 
XML, JSON, HTML, and all such are now open doors for our web applications. 

But, for now, our forum is switching statically between pages all the time 
(read: loading the full page), and sometimes requests that we go back and 
refresh the page to use it further, such as refreshing a chatroom to see other 
participants' new messages. 

So, what's missing now? Dynamic client behavior. That's exactly what will be 
covered in the next chapter. 




Moving to Real-time 
Web Applications 

A web application, nowadays, is expected to be as reactive as a desktop one; moving 
statically from one page to another is no longer accepted. Furthermore, to enhance 
the user experience, we need to reduce as much as possible the amount of actions 
needed to have the content updated constantly. 

We entered the real-time era some time back, and the mobile explosion has 
definitively confirmed that. Given this fact, the problem we face when creating a web 
application dedicated to mobile devices is, still, the bandwidth (this doesn't seem like 
we have entered the same era as our needs). So, we'll have to think more about some 
optimizations while communicating with the server. This chapter is dedicated to the 
utilities Play! Framework 2 is offering us to enable us to satisfy these points. 

The following is what will be covered in this chapter: 

• Creating a dashboard, where the data will be updated in the background 

• Following the naive approach using a polling service over HTTP 

• Introducing CoffeeScript before using it for client-side logic 

• Adapting the dashboard a bit to use dynamically updated forms 

• Doing a final update of the dashboard using WebSockets 



At the end, we'll have a good overview on how to replicate the solution to other 
similar needs. 
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Ready, JSON, poll 

In the earlier chapters, we built an application that mixed the notion of a chat and a 
forum. If we use it, we'll face some problems for sure; indeed, when we post a new 
message or image, the other users that are connected won't be notified unless they 
refresh their whole page. This kind of workflow is a pain in terms of performance 
and user experience. As it requires several users' actions, and because all data has 
to be provided by the server (which will give the same stuff again and again); think 
about big images that are loaded each time the application is refreshed. All of this 
tells us that such a workflow is not optimal at all. How are we going to tackle this? 
First we will use the ancestral polling system. 

Polling is a system asking the server (or a bunch of services) the same resources 
repeatedly, and, normally, at a high rate (the higher it is, the better user experience 
you should have). So, it's trivial that it'll consume a lot of power, and often wasted 
because the requested state in the server hasn't changed. Project this problem in 
a mobile application and it can empty the battery quickly. We'll achieve this by 
rendering our resources in a more convenient way using JSON, and by having 
some JavaScript scripts on the client side to fetch them. 

To make our application more user-friendly, we'll create a kind of dashboard that 
can be customized to include those interesting chat instances / topics for the user. 
Thanks to this use case, we'll also see some other helpers provided by Play! 2 in 
order to dynamize forms on the client and the server side, through the need of the 
non-deterministic structure (list). 

The second thing we will resort to here will be the use of CoffeeScript rather than 
JavaScript (in some sense). Because the Play! 2 Framework is perfectly integrated 
with CoffeeScript, we will be able to use it like we were using simple JavaScript 
scripts. Indeed, Play! 2 will handle the compilation and hot refresh on its own. Its 
official website (http : //cof f eescript . org/) defines CoffeeScript as follows: 

CoffeeScript is a little language that compiles into JavaScript. 
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Coff eeScript is a language that eliminates boilerplates or 
enables class definition (among other things). Furthermore, 
it has the advantage to be compiled into a readable 
JavaScript file (helpful for debugging, for instance). 



] 



One of the reasons we'll use CoffeeScript over JavaScript is because it is more 
readable for most server-side programmers (the syntax is similar to Python). 

So, we want a dashboard, which is something that presents a lot of things at the 
same time, in order to multitask optimally. Let's do it. 



Configuring a dashboard 

A dashboard is something that can be configured to present the exact amount of 
information that a user wants to see. So, in our case, where only chat instances are 
involved, we're going to provide a way to see several chat instances at once. 

For that, we'll have to deal with a dynamic form on the server side. This form will 
be such that the number of values passed to the server is neither predetermined nor 
fixed (non-deterministic). 

First of all, we'll need a new template for this and its related server-side action. The 
template will present an HTML form, where the user can select which chat instances 
he/ she wants to add to his/her dashboard. So we'll need all available chat instances 
as a parameter of this template in order to create the UI that enables such selections. 

On the server side, the action should be able to retrieve as many chat instances as 
the user has configured; hence we're going to have a kind of dynamic list of chat 
references to be bound to the request content. 
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The following screenshot shows an example of how we can define our template: 



1 @t dashboa rdFo rm : Farm! cont rollers . Dashboard . Data] , all Chat s : List [ Chat ] = Nil J 

2 

3 @* Even inner template can be defined as simple as function def imtion*@ 

4 @createSelect ( slid : Field, preparedChats : Seq[ ( St ring, String)]) = { 

@helper . select i elld, preparedChats, '_l a bel -> "Chats", 'class »> "selectChat " ) 

6 } 

@* defining enables to keep a specific computation in a dedicated variable *@ 

5 ^defining t all Chat s . map t c =» i c . internalld .toSt ring, c .topic) ) .toSeq) { preparedChats =» 

9 

@main[ "Welcome on Play! 2 - ChatRum") { 

11 <div id="dashboard"> 

12 <div id="loader" * 

<span class="header" title="Click to toggle" -Change Chats or create- span- 
14 <div class="container"> 

15 

1G @* *** + + * + ** + * + + ****** + + * + * *@ 

17 @* TO BE USED BY JavaScript *@ 

IB @* ************************ *@ 

19 -div class="sampleJsBlock chat" style=" display : none; "> 

@createSelect (dashboardFormt"chatIds[x]"i , preparedChats) 
21 div » 

22 
23 

24 (B* ******************************* *g 

25 @* Form definition to select Chats »g 

26 @* ******************************* *@ 

tahelper , formi action=routes , Dashboard , open, 'id -» " select Chat s" ) { 

2B 

'div id="chatSelectors"> 

33 e* iiiuniiuiuiuitiiii *@ 

31 @* REPEAT HERE ! mm => 2 *@ 

32 @* /////////////////////// *e 

@helper , repeat ( dashboardForm( "chatlds" ) , min=2) { chatld => 
@createSelect ( chatld, preparedChats) 

35 > 

div> 

37 

38 @* A ' + ' BUTTON to add new Chat 'select' boxes »@ 

■input id="addChat Select or" t vpe= " butt on " val ue= ° + ° /> 

40 

41 br. '> 

42 --input t ype=" submit " •/alue="Open" 

43 } 
44 

45 @* Create a new Chat rather than show some other f@ 

<a href="@routes . Chat s , registerChat !l " .-Create a new one*, a- 
47 </div 
40 ■ div> 

49 

50 <=/div=- 

51 > 

52 } 



What we see in this example is interesting in several ways. First of all, while 
defining a dashboard for our chat system, we tried to split the tasks in order to 
improve readability. 
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For that, we created an inner template createSelect that takes a form field and a 
sequence of a tuple of strings. The result of this template is an Html block that shows 
an HTML select element. It has been defined against a parameter of type Field, 
which is just a wrapper around all information that is necessary to show an HTML 
element in an elegant and valuable way — the name, ID, errors, constraints, and so 
on. These instances can be easily built from the Form instance based on their expected 
name in the request. 

We can also see that in order to define an inner template, we simply have to define 
a function. This is quite intuitive because we already saw that Scala templates are 
compiled into a Scala function. 

Then we took all the existing chat instances (available as a parameter of the template) 
in a sequence and mapped them to a representation that is easily usable byaselect 
input field. 

As this computation will be done more than once, we can define it as a new variable, 
preparedChats, through the use of the helper defining. As it's not possible to create 
new variables within a template, we can use this helper that takes a computation and 
a block of code that uses it. This is done by providing a function that takes the result 
of the computation as the only argument. In this case, the function block of defining 
is creating Html content to be rendered. 

Now we're reaching two exciting blocks as we're about to define the dynamic part of 
the form. Recall that we're trying to have a form that enables the user to select several 
chat instances to be shown on a single page. 

Let's skip the very next block with the class sampleJsBlock, and first look at form 
one, where we start directly with the action definition that targets a new dedicated 
action (routes . Dashboard . open), followed by the usage of another helper: repeat. 
This helper is indeed a very useful one (because it will hide for us all boilerplates 
necessary to create form elements that must be serialized under the same name) and 
is followed by an array index. 

HTML enables a parameter to be defined multiple times by simply 
using the same name. However, there is a common pattern to handle 
a use case that adapts this specification. The solution is to follow the 
name with either empty brackets or brackets holding the index of a 
value. Play! 2 uses the second convention, and so using the repeat 
helper we'll have solutions such as param [0] =a and param [1] =b. 
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Furthermore, this helper has a specific argument telling us how many times 
its body definition has to be generated. In our case, we want at least two chat 
instances to be shown. This so-called body, in our case, is exactly a call of our 
inner template createSelect, which will create a select element containing 
all available chat instances. 

We shall go to the action now in order to check how the heck this parameter list 
will be handled. But before that, it'd be worth looking at the block we kept aside, 
which is there to enable the user to add more than two chat instances to his/her 
dashboard, dynamically. 

To do that, there is a common trick (a kind of pattern) that will enable us to create, on 
the client side, a UI that matches exactly what is produced on the server side (using a 
template and thus helpers). This is achieved by creating a dummy excerpt of HTML, 
and hiding it outside the form tag. This is what has been done with the div tag 
having the class sampleJsBlock. In fact, this one just contains a generated select 
element, but with a dummy field (giving dashboardForm the expected name, but 
with a fake index). 

In order to catch what will be necessary to do with it, it's important to check what 
is produced: 



Chats 



Talk, it's only talk • 



Chats 



□ 
| Open | 

Create a new one 



□ 



1 Resources 



T <ht ml > 
► <head>...</head> 
t <body> 

■shl^Connected as me@home , org*:/hl> 
» <sc npt >...</ script > 
T-sdiv id="dashboard"> 
T <di v id="1 oader "> 

<span class="header" title="Click to toggle">Change Chats or create-=:/span> 
T<div class= "container" style=" display : blockj 



▼ <dl class=" " id=" chat Ids x field" 

T<dt> 

<label f or=" chat Ids_x_" aChat s</label> 
t <dd> 

► <s elect id= "chatlds_a:_" name=" chat Ids [ x 1 ">„.</select> 
</dd> 
</dl> 
</div> 

v <f o rm act ion=" /dashboard/open" met hod=" POST" id= "select Chat s"> 
► idiv id="chatSelectors">.,.i/divJ> 
<input id=" add Chat Selector" t ype=" butt on" ualue="+"> 
<br> 

<input type= "submit " value= "Open" > 
</f orm> 

<a href="/f orra/chat ":>Creat e a new one</a> 
</div> 



[□ >- Q html body riivffdashboard drvffloader div.contairver 



div. sampleJs Block.*: hat 
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We can see that there is a hidden div tag defining some elements, which has 
attributes containing the provided dummy index, namely _x_ and [x] . 

So you can surmise that we'll have to produce a client-side code (we'll do it in 
CoffeeScript) that takes this bunch of HTML and replaces all such instances of the 
dummy index by the current count of selects being shown (starting at 2, though). 

Let's keep this in mind and perform a quick hook in the controller to check how this 
form is bound to an instance of controllers . Dashboard . Data according to the type 
of template parameter, dashboardForm. 

The controller that we're talking about is the one targeted by the form in its action 
attribute, which is Dashboard: 



public class Dashboard extends Controller { 

static public Forin-c:Data> dashboardForm = f orm( Data, cl ass] \ 






public static Result indexU i. 
return ok( 

views .html .dashboard. index. renderfdashboardForm, Chart . find . all ( ) 

) l 


, Chats . it emFo rm 


Chats , imageForm) 


} 

public static Result open( ) ■£ 

Form<Darta> dashboardForm = form ( Data, class) j 
Form<Data> filledForm = dashboardForm . bindFromRequest () ; 
if(dashboardForm,hasErrors( ) ) { 
return badRequest( 

views .html .dashboard. index, renderffilledForm, Chat , find , all ( ) , 


Chats, itemFormj 


Chats , imageFo rm) 


1; 

} else { 
return ok( 

views .html .dashboard. index. renderffilledForm. Chat . find . all ( ) , 

); 

} 


Chats. itemForm, 


Chats . imageFo rm) 


} 

public static final class Data { 

public List<Long> chat Ids = new Arrayl_ist<l_ong>( ) j 






public List<Chat> chats( ) { 

List achats- cs = new Arrayl_ist<Chat>( j ; 
for (Long 1 chat Ids] { 
Chat c = Chat. find. byld(l) ; 
if (c != null) { 
cs . add( c) ; 

} 






} 

return csj 

> 

} 

> 







The Dashboard controller is very straightforward and doesn't include any new stuff 
that we need to point out. The only thing that is really interesting is the Data inner 
class, which stands as a container for the received chat instances' IDs. 

As done earlier, we use the form method to create the binding by reflection. This 
binding will take into account the list and will expect several values with the same 
indexed name. So, we're binding it with the request as usual in the open action. 



Moving to Real-time Web Applications 



Something to note from here is that we're going to use the same template for 
rendering the form and the dashboard itself; that's because we'll not change the 
dashboard's configuration even if one is already opened. As a consequence, we'll 
have everything in the same template. 

It's now time to dynamize the form using CoffeeScript. 



Some sugar with your Coffee(Script) 

So what we need to do is enable the + button to take the sample HTML block created 
on the server side to add a new select element after the existing ones. This block 
must be reworked a bit in order to use the correct index; we'll do that in CoffeeScript. 

To be able to code in CoffeeScript using the same techniques as Java or Scala (hot 
recompile and reload, for instance) we can put our .coffee files in the folder app/ 
assets/ javascripts/. Hence, we'll create the file app/assets/ javascripts/ 
dashboard . coffee. 



[ 



Obviously, coffee is the extension of a 
CoffeeScript file. 



] 



As said earlier, CoffeeScript is there to help developers by eliminating a lot of 
boilerplates, mostly in order to code in a more object-oriented fashion using 
classes — for those who want this paradigm back. 

The code in the following screenshot shows how we can implement our use case: 



OPEN FILES 

Dashboard. java 
Application. java 



dashboard, coffee 



chatroom. coffee 
FOLDERS 
T play-jbook 
.settings 
T app 
T assets 
T javascripts 

chatroom. coffee 



dashboard. coffee 



► stylesheets 
comparison 
T controllers 

Application. java 
Chats.java 



Dashboard. java 



Application. java 



dashboard. coffee 



class Dashboa 
const ructor 
@el = opt 

# The div 

# which h 

# their 
@header = 
@header , o 

S(W ■ 
if i o pt 
@header 

# Enable 
@el . find 

tmpl = 
count : 

# take 

# repl 
newCont 



rd 



4 

5 
6 
7 
8 
9 
1G 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 

25 window, Dashboard = Dashboard 



#put th 
@el . fin 



(opt! -> 
el 

in the root element of the dashboard 
s "header" in their classes will toggle 
content (its following element) 
@el . find i " . header" i 
i "click", II ■> 

xt ( i .toggle 1 1 slow 1 i #on click toggle the next element 
1 osed i 
eq( Oi . click( i j 

the '+' button to add new select boxes dynamically 
"#addChatSelector" l . on "click", I! => 
$( " . samplelsBlock . chat " i 

@el . find 1 . " . select Chat " I .length 
the template html block as text 
ace the s's by the current count 
ent = t m pi , ht ml 

. replace' f\ [\{_\\%\ E\I_II/g* "$l"+CQunt +"$2" 
e new content at the end of the according block 
d ( "#chat Sel ect o rs " i . append « newCont ent ) 
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Even though we're using the basic features of CoffeeScript in this example, it is 
intuitive enough to get a big picture. However, there are still some concepts that 
might be worth mentioning. 

Words about CoffeeScript's syntax 

An important thing to know about CoffeeScript is that its layout is actually driven by 
the spaces used to indent the lines (Python style). Take a simple example: the body 
of a function must be indented one time more than the function declaration's indent. 

As a consequence, CoffeeScript doesn't require parenthesis for a parameter's block 
and nor does it require a comma to separate the array's items or properties in an 
object (if they are separated by well-indented blank lines). 

A class can be defined as easily as in an object-oriented language, that is, by simply 
using the class keyword followed by the class name. Methods and fields can 
be defined using the Ob j ect notation, that is, the name followed by a colon, and 
then the definition of the field or the function. A commonly used method is the 
constructor one, which will be used when using the new operator. 

A variable declaration is not defined by any special keyword (such as var); actually, 
all newly used variables will be created locally by default (rather than globally, as in 
JavaScript). 

A function can be declared in two ways: with an arrow (- >) or a fat arrow (=>). These 
arrows will separate the function parameters between parenthesis and the body of 
the function (the implementation). The only difference between the arrow and the fat 
arrow is that the latter will keep the actual scope (which is graceful when playing with 
closures); the this object can be kept as the original class' object, for instance. 
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The following screenshot shows two functions for illustration purposes: 





class A 














constructor: |v] -> 












3 




@v = V 












A 

*\ 


















f : 


( i) ■> 












□ 




console, log ij 












s 




console .log^ 












p 
















G 




i i i => 












± u 




console ,log- i 












± ± 




console ,log' @v 1 












i. j£ 
















Id 


a = 


new A' "I'm a" i 












1 d 
± *+ 


b = 


new A 1 "I'm b" i 












15 
















16 


a.f . 


call 1 a, "Will print 


» 


I 


in 


a" i 




17 


# $> 


Will print » I'm 


a 










18 


# 


I'm a 












19 
















2Q 


a . g . 


call 1 a, "Will print 


» 


I 


m 


a"i 




21 


# $> 


Will print » I'm 


a 










22 


# $> 


I'm a 












23 
















24 


a.f. 


call 1 b, "Will print 


» 


I 


m 


b" i 


##### BANG 1 #### 


25 


# $> 


Will print » I'm 


b 










26 


# $> 


I'm b 












27 
















28 


a . q . 


call 1 b, "Will print 


» 


I 


m 


a" i 


# this has been bound to al 


29 


# $> 


Will print » I'm 


a 










30 


# $> 


I'm a 













To read the example, we must mention that the this variable doesn't exist, but @ can 
be used to refer it; so ©prop is compiled as this . prop. 

Now we can understand that the g function, which makes use of the fat arrow, will 
never lose its initial scope, that is, the object that holds it. 

Explaining CoffeeScript in action 

Back to our Dashboard class, we can see that it only defines its logic in its 
constructor, so it doesn't provide any other functionalities besides starting itself 
with some actions. These actions are twofold (using jQuery that was imported 
in the main template): 

• The first action is retrieving all the elements that have the header class. 
On them, it will register a click event that will toggle the next DOM 
element. Another initial parameter is used to tell if it should close these 
elements on startup. 
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• The second action registers a click event on the + button that will look for 
the block of HTML code in the form that wraps all select elements, then 
keeps count of the already present ones, and finally retrieves the hidden 
template's excerpt, so it will update the template with the relevant count 
and then append it to the block. 

In brief, this . coffee file defines the Dashboard class and makes it available in the 
global scope in the very last statement. Having created this file, there are two things 
to be done - add the compiled JavaScript file to the web page and use it. 

Play! 2 will compile our CoffeeScript file in the same folder as our traditional 
JavaScript files, that is, in the public/ j avascripts folder. Because of this, adding 
them to the application is as simple as adding a new JavaScript library in the scope 
(most of the time, this will be done in the main . scala . html file). This way, Play! 2 
will be able to cache it and do some JavaScript minification for the production mode 

The way we're going to use it is not very conventional, but it will do the trick. In 
our dashboard/ index, scala .html file, we'll just add a bootstrap code creating an 
instance of this Dashboard class: 





g* defining enables to keep a specific computation in a dedicated variable *@ 


10 


(3defining( all Chat s . map ( c => ( c . internalld .tost ring, c .topic) ) .toSeq! { preparedchats => 


11 




12 


@main( "Welcome on Play! 2 - ChatRum") { 


13 




14 


<script > 


15 


$ ' function 1 ' { 


16 


dashboard = new Dashboard 1 { 


17 


el : $' "^dashboard" I , 


18 


closed : @dashboardForm , value , isDef ined 


19 


})j 


20 


> i J _ 


21 


<Jscript> 


22 




23 


'div id=" dashboard"- 



• In a real application, it's worth considering libraries such j 

\%/\ as Spine . j s or Backbone . j s with Require . j s for I 
^"""^ organizing your code and loading them. I 



Rendering the dashboard 

Until now, we've been able to tell the server which chat instances are to be shown 
in the dashboard, but we haven't showed them yet. However, in the action, we saw 
that we're rendering the same template by providing the updated form with a Data 
instance, which has a helper method to fetch the chat instances. 
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Here again, we'll take advantage of the composability of our templates, by re-using 
the chatroom template for each chat in the chat instances list; the only thing we have 
to do in it is remove the call to main. 

As this template requires two more parameters (the form enabling new messages 
or uploading of images), we're going to add them to the dashboard/ index . scala . 
html template's signature. 

What comes next is fairly obvious. Check out the following screenshot: 

~- @! 

dashboardForm: Form[cont rollers, Dashboard, Data] , 
all Chats: List [Chat] = Nil, 
it emFo rm : Form! Item] , 
sendlmageForm : Form] Image] ] 

6 
7 

8 @ f Even inner template' can be defined as simple as function def init ion • (a 
@create5elect ( elld : Field . preparedChats : Seq[ t St ring. String)]] = { 

@helper . select ( el Id, preparedChats, '_label -> "Chats", 'class ~> "selectChat " ) 

11 > 
12 

13 @* defining enables to keep a specific computation in a dedicated variable *@ 

14 ^defining! allChats , map( c => ( c , internalld ,toSt ring, c , t opic ) ) , t oSeq ) { preparedChats => 



1? 
16 
17 
18 

2D 
21 
22 
23 
24 
25 
26 
27 
23 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 



} 

> 



@main( "Welcome on Play! 2 - ChatRum") { 



I function' ' { 

dashboard = nev Dashboard 1 { 
el : $> "#dashboard" ) , 

closed : @dashboardForm . value , isDef ined 

}); 

</script> 



} 

< div 



-=div id="dashboard" ■ 
■=div id="loader" 
</div 



i3defining( dashboardForm . value) {data => 



@if tdata.isDefinedl { 
<div> 



} 
div 

} 



ijdata , get , chats , mapi c => 



@chat room i c , itemForm, sendlmageForm) 




The action doesn't need to be changed as it 
has foreseen them. 
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That was easy game. We just checked whether the form contains some data; if so, we 
looped on the embedded list of chat instances and called the relevant template. 

The following screenshot shows the result (with a bit of skinning) we have so far: 



Talk, it's only talk 



So far... 


Attached Images 


♦ [08:47:54.252] thief@hood.com > yeah 

* [08:47:54.276] me@home.org >true 

« [08:47:54.277] thirf@hood.com > indeed 




React 


Attach an image 


message 


caption 


1 


1 


Maximum length: 140 
Required 

send | 


Maximum length: 140 

pic 

Choose File | No file chosen 

send 



News... 


So far... 

• [08:47:54.278] no@one.biz> new HashMapO 

• [08:47:54.281] me@home.org > new Date() 

• [08:47:54.28 1] thief@hood.com > Men... 


Attached Images 



This is what we get after having selected two chat instances in 
the form; we can also see that the form is hidden (that came 
from the bootstrapping JavaScript that told to close it when a 
Data instance is available). 



Updating the dashboard in live mode 

So far so good— we have an aggregated view on several chat instances, but what 
hasn't been satisfied yet is the "liveness" of the updates. Actually, this problem has 
taken on more significance now, as several chat instances are involved. So let's 
resolve it. 
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What we're about to do is enable a poller for each chat to fetch its last updates that 
are available. For that we'll need two kinds of things, as follows: 

• A bunch of JavaScript files that run in the background in order to constantly 
fetch items and images based on the last timestamp. The result, a JSON, will 
be used to update the UI. 

• An action on the server side taking a timestamp and a chat that will return 
a JSON-encoded response with the items and images created since the 
given timestamp. 

For the first part, we'll do quite the same as we did in the earlier section, that is, 
create a . coffee file that will contain the logic, add it to the main template, and 
initialize it in the relevant template. 

First, the . coffee file! We'll create a new one, named chatroom . coffee, which 
could be as shown in the following screenshot: 





class Chat Room 






const ruct o r : ( conf ) -> 




3 


@id = conf . id 




4 


@el = conf. el 




5 
6 


@since = conf. since 




7 


■formatTimestamp: (ts) - > 




8 


ts , values! H] + ":" + ts . values! 1] + ":" + ts.values[2] + "." 


+ ts . values! 3] 


9 
10 


updateList: (target, list, "format) => 




11 


c = t a rget . f ind'. "ul " i 




12 


$■ list i . each 1 ( ids, item) => 




13 


c , append' ' <\i clas5="item "> '+1 : orniat i iteini + ' <£Li>' i 

) 




14 




15 






16 






17 


updateChat : ( items, images) => 




13 


@updat eList ( 




19 


@el . find 1 " . react . past " i , 




20 


it ems , 




21 


(l) => 




22 


1 <span cljs i s^^iiej>[ ' + @-formatTimestamp' i. tiniest amp < + 


]</span> <span>' +i . user . email+ '</span> > + i. message 


23 






24 






25 


@updatel_ist( 




26 


@el . find 1 " . attach . past " ) , 




27 


images , 




23 


lil => 




29 


cap = l . caption 




30 


cap+ ' : ^irno, sr^=Vc^at/^Bj^es/ 1 + i . int ernalld+ '" alt= 


' ' + cap+ 1 " t itl e=" ' + cap+ ' 


31 






32 






33 


■fetchContent : => 




34 


me = @ 




35 






36 


"^^XIS9I&^n^/" + + " XtiPlJJlJJILEx " + @ s i nce J 




37 






38 


(data) -> 




39 


me . updat eChat 1 data .items, data.images) 




40 


m e . p ol I ( i 




41 


me. since = new Date 1 i .getTime 1 i 




42 






43 


: 




44 






45 


poll ; => 




46 


setTimeout' @f etchContent , 5000i 




47 






43 


window , Chat Room = ChatRoom 
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So what's the big deal here? 

The constructor of chatRoom takes a configuration object with three properties kept 
as fields of the class: the chat's ID (id), the element (el) wherein the UI has been 
added, and the last updated timestamp (since). 

At the end of the class definition, there is a poll method, which simply starts an 
endless loop over the f etchcontent method right above it, every 5 seconds. This 
latter method (thanks to the fat arrow) is always resolved to the actual instance, and 
its work is actually to call the server-side action that will be tackled next. 

For that, we used jQuery's a j ax function (get is just a jQuery abstraction over it) by 
giving it a URL filled with the expected parameters and a success function that will 
handle the response (a data encoded in JSON). 

When the call succeeds we ask the ChatRoom class to update its UI with the new data, 
and we call poll again. 

Think about what is so bad here — ! The URL was hardcoded! 

This will be resolved in the next chapter. Other things that can be 
r^STX improved here are the building of the items and images on the UI. 
^fc^-^ Actually, we could re-use the tip we used earlier with the hidden 

HTML excerpt. That is, we could create the HTML with some 

placeholders to be replaced using JavaScript. 

After including this script in the main page (<script src= "... "), we must update 
the chatroom. scala.html template to initialize an instance of ChatRoom, shown 
as follows: 



1 @( chat : Chat , item : Form[ Item] , sendlmage : Form[ Image] ) 

2 

3 @import helper. _ 

4 

5 

6 <script> 

$ function -f 

/♦ChatRoom is defined in chat^room . coffee => compiled in djyat^noom . jjs 
9 » this is file is imported in main.scala.html 

1G */ 

11 var room = new ChatRoom 1 { 

id: @chat . internalld, 
el : f I "#chat room_@chat . int e rnal Id " ) , 

14 since: new Date' i , get Time' i 

15 )); 

16 room . poll ( ) ; 

17 }); 

18 </script > 
19 

20 @* REMOVE => @main( "Chat Room : " + chat . int e rnal Id j { *@ 

21 <div id= " chat rcom_@chat . internal Id" > 
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One last thing to have the whole polling system in place is to add the action to be 
routed from URLs such as /chat/content/ : id?timestamp= : since. So this action 
should take two arguments: two Long types (one for the ID and the other for the last 
update timestamp). 



public static Result content Since! Long chat Id, Long timestamp) { 
Local Time t = new LocalTimei! timestamp) ; 
Object Node result = Json. newObj ect ( ) ; 
Chat chat = Chat . find . byld( chat Id) j 
if (chat == null I < 

result , put ( "error" , "chat not found"]; 

return notFoundl result ) ; 

} 

List<rtein> items = chat, it ems; 
List<Item> ritems = new ArrayList<Item>[ ) ; 
List<Image> images = chat. images; 
List<Iinage> rimages = new ArrayList<Image>i ) ; 

for (Item i : items) l 

if t i .timestamp! ), isAfter(t ) ) { 
ritems , add( i) ; 

> 

} 

for (Image i : images) { 

if C i .timestamp! ]. isAfter(t ) ] I 
rimages . add( i) ; 

} 

} 

result . put ( "items" , Json. to Json! ritems] ) ; 
result. put ("images", Json. to Json (rimages )) ; 
return ok[ result ) ; 

} 



Quite obvious, we just retrieve the chat instance and filter the items and images 
based on the given timestamp (wouldn't it be great to have a higher function filter on 
the lists?). Then we asked the JSON from Play! 2 to encode an object containing both 
resulting lists (using reflection and thus without our help). And we're done. We can 
now open several browsers, configure our dashboard, and do cross-chatting with 
them all. And magically, everything is updated automatically. 

Amazing, right? But not enough. Because, at first, we hardcoded URLs, then we 
polled for each chat instance. We also have the same forms for posting new items or 
images for each chat instance, but using them will cause us to leave the page and will 
force us to go back in order to go back to the dashboard. 

So annoying! That's why we're about to change that in the next section. 

Dynamic maintains form 

In the previous section, we made another improvement to our application by 
enabling some live updates while using the dashboard, all this using a polling 
system that targets a dedicated action. 
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However, we saw that it wasn't enough to excite the "chatrumer"; indeed, each time 
he/ she posts a message or a file, he/ she will be redirected to a new page. That's not 
what we call a "user-friendly" interface. 

[r^STX Chatrum: A fancy combination of chatting I 
^fc-^ and forum. I 

Moreover, we did a very wild thing with the code, which was the hardcoding of a 
URL— that's so scary. 

To recover our peace, and the user's, we're going to use the amazing features that 
Play! 2 is providing us with: a client-side router and a JavaScript version of the 
server-side router which was used to perform redirects and so on. Both the server and 
the client routers are generated by Play! 2's code generator based on the routes file. 

Going even further, we'll reduce the number of forms (for posting) from twice the 
number of chatrooms being shown to only two, simply by introducing a selector that 
switches between them. The plan is set; so let's do this reduction by removing the 
form's parameters from the chat room template and put them back in a dedicated one 
called participatingChats. 



participatingChat5.5cala.html 



1 @( 

chats: List [Chat] = Nil, 
it emFo rm : Form [ Item] , 

4 sendImageForm:Form[Image] 

5 ) 

6 

7 ^import hel. pe r . _ 

8 

9 <div class="int eract row"> 
-select id= " chat Sel ect " > 
(achats . map{ c => 

--option value="@c . int e rnal Id " >@c . t opic</ option ■ 

13 } 

-/select - 

-=:div class=" react " =- 
-=:h3>React- h3 
17 -=:forin id="talk"> 

tainputTest ( itemFormf "message" ) ] 
19 input type="submit " va~lue="send"/> 

2Q </form- 
21 </div> 
22 

-=:div class="attach"> 

-=:h3>Attach an image</h3> 
-form 

id= "sendlmage" 

a ct i o n= " # " m et h o d= " POST" 

e n ct y p e= " in ul t i p a rt / f o r m - d at a " > 

ItainputText ( sendlmageFormt "caption" ) ) 

3G 

@input Fil e(sendImageForm( "^ic " ) ) 

32 

-input type="submit value="send"/> 

34 </f aw 

35 </div> 

36 </div> 
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As the changes to the chat room template are pretty straightforward, we'll only look 
at what's going on in the newly introduced template. 

Not that much actually, we just picked up the HTML block from the chatroom 
template and dropped it in a new one. But we did two surgical modifications: one 
related to the HTML form's definitions and the other one that creates a selector with 
all chat instances being shown in the dashboard. 

What has been done is revert the use of the helper . form template provided by Play! 
2, which will generate a form on the server side with a fixed action (using a Call 
instance), to the classical HTML one. Looking closer, we can even see that the 
actions haven't been set and have a dummy value such as #. So, are we expecting 
some CoffeeScript? 

Just before entering these details, we mustn't forget to call this template somewhere. 
As its responsibility is to enable the user to select the chat that he/ she wants to 
interact with a message or an image, it'll be used in the dashboard/index . scala . 
html template, shown as follows: 



-=div ici="dashboard"> 
-=div id= "loader" -q 
</d±v> 

@defining( dashboardForm , value) {data = > 
@if ( data . isDef inedj { 
<div> 

@defining( data . get . chatsH chosenChats => 
@chosenChats . map{ c => 
@chat room( c) 

} 

(3pa rt icip at ingCh at s( chosen Chats, itemForm, sendlmageForm j 

} 

</ div> 

} 

} 

■ div> 



What we did is simply add the forms right after adding the chat instances, outside 
the loop. As we're going to use the sequence of all shown chat instances, we've also 
created a scoped variable (still using the defining template). 
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At this stage, we can already run the code and see something like the following 
screenshot; however, nothing is going to work since the action attributes haven't 
been set on the forms. 



Talk, it's only talk 



So far... ! Attached Images 

• [17:23:56.207] thief@hood.com > yeah : 

• [17:23:56.219] me@home.org > true ; 

• [17:23:56.219] thief@hood.com > indeed : 

• [17:29:46.365] tliief@hood.com > coucou : 



News... 


So far... 

• [17:23:56.220] no@oiie.biz > new HashMapO 

• [17:23:56.221] me@home.org > new Datef) 

• [17:23:56.222] tliief@hood.com > Men... 


Attached Images 



Attach an image 

caption 

I 

Maximum length: 140 

pic 

| Choose File | No file chosen 
| send | 



What do we have to do with this now? The forms need an action to be set and they 
cannot change the current page. 

First the URLs. The problem with our URLs is that they are presenting information in 
them, such as the target chat's ID: 



If 

28 
29 
30 
31 


GET 


/chat/content/ : id 


cont roL Lers 


Chats 


cont ent Since i, id : Long j times" 


POST 


/chat/ : chat/message 


cont rollers 


Chats 


talk( chat : Long) 


POST 


/chat/ : chat/image 


cont rollers 


Chats 


receivelmage( chat : Long) 


32 













What we did earlier was to extract the URL manually from the routes file, and 
generate the URL ourselves (for the polling). But there is a smarter way to do this in 
Play! 2, that is, using a JavaScript reverse router. 



Talk, it's only talk » React 

message 



Maximum length: 140 
Required 
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What is this router? It is a JavaScript object that contains a representation of certain 
server-side actions that we've expected will be used on the client side. In our case, 
we'll create such a router entry for the actions talk and receivelmage. 

Creating such a router is pretty simple. The idea is to ask Play! Framework 2 to create 
a JavaScript file that can be imported in an HTML page (in our case, in the main one), 
as we do for any other JavaScript file. 

So first we need an action that creates this file and its route definition. Such an action 
will use a builder that Play! 2 provides us, which is Routes . j avascriptRouter, 
with the help of the compiler that generates a JavascriptReverseRoute route for 
each action. 



Now check out the following screenshot: 



21 


public class Application extends Controller { 


22 




23 


/** 


24 


* JavaScript version of the router to be injected in the main page 


25 


*/ 


26 


public static Result jsl) { 


27 


response! ] . set Content Type( "text/i avascript " ) ; 


28 


return ok( 


29 


Routes. javascript Router! "pi ay Router" , 


30 




31 


controllers, routes, javascript. Chats. talk! ) .. 


32 


controllers, routes, javascript. Chats, receivelmage! ) , 


33 ) 


34 


) ; 


35 


} 







Good! What has been done in the previous screenshot was first setting the content 
type of our HTTP response to be text/ j avascript, and then building this 
embedded file to be sent with an OK status. 

To build such a file, we first call the utility method in Routes called 
j avascriptRouter that takes two arguments: 

• The first is the name of the JavaScript object (the name that will be available 
under window on the client side). 

• The second is a varargs of JavascriptReverseRoute; such routing instances 
are created for our good by the compiler. Each time we define a route to 

an action, this action will be reverse-routed in an object located under the 
package controllers . routes . j avascript. 
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That's fine; this will generate the JavaScript file containing the reverse-routing part, 
but now we have to route it too and call it in our main template. The following 
screenshot shows the routing, and how we can use the j s action with a script tag: 



# Content 

GET /cha^ijja^esjf ; imageld cent roll ers . Content , getlmage( imageld : Long) 
GET /coirj^rt^ s controllers. Content , at om( emails : St ring) 

# Map static resources from the /public folder to the /assets URL path 



GET /assets/+file 
/j^oj-rtes 



cont roll e rs . Asset s . at ( pat h=" /publ ic" , file) 
cont rollers. Applicat ion. js( ) 



main.scala.html 



<Link reL="st y Lesheet " meaia=" screen" nret= "(drout es . Asset s . at \ "s^lv^s^^^vfc - 1 " > 

<link rel = "sho rt cut icon" t ype= "image/ png" href="@rout es . Asset s . at ( "images/f auicon . png " ) " >< 
^script s rc="@rout es . Asset s . at "i a vase ript s/i guery -1 . 7. 1 . min . i s" " t ype="t ext /] avasenpt " >< fscript> 
^script s rc="@routes . Asset s . at ( ' ~ '■ = ~. X^^^^iU 



<script s rc= " @ rout es . Asset s . at ( "^javas^^ type="tej(t^j|^^ 

<scripi s rc="@ rout es . Asset s . at ( " Jjavasc^^ .js" ) " t ype=''tjejd^^ "></script> 

<!-- import js reverse routing --> 

<script src='@rQutes, Applicat ion, |s' type= ' t^ejjt/ja^^cn^ ' ></script> 



As expected, we simply routed the actions to a custom URL that we used in our 
template like any other JavaScript (or CoffeeScript) file. 

So, what's available now on the client side? Let's check it in the browser: 

Proffes ! —^ Audits Consofe 



_ Elerroents J Resources \^ Network 

> playRouter 
* Object 

' controllers; Ob] ect 
t Chats : Obj ect 
* receivelmage : function (chat) { 
► talk 5 f unct ion ( chat | f 

^ proto : Ob] ect 

► prot a : Obj ect 

► prot o : Obj ect 

> pi ay Rout er , cont rolle rs . Chat s .t alk 
f unct ion ( chat I { 

return _vA( {met hod : "POST" , url:"/chat/' 
} 

> pi ay Router , cent rolle rs . Chats .talk ( 1000Q0] 
T Object 

► absoluteURL: function (sHreturn _s( 'http 
* aj ax : function ( cffc.il rl= r.urljc.type=r.method;return j Que ry . aj ax ( c) > 

method: " POST" 

url : "/chat/lOOOOO/message" 
*■ webSocket URL: function ( s] {return _s( 'ws ' , s) + 'local host : 9000' + r . url} 
► proto : Object 

> pi ay Rout er . cont rolle rs . Chat s.talk(l) . ajaxH 

dat a : { message : "From Is"}, 
success : f unct ion ( resp) { 
ale rt ( respl j 

> 

» 

*■ Ob] ect 



( f unct ion [ k , v) {ret urn v} ) ( "chat 11 , chat ) 



'local host : 9000' + r . url} 



"/message"}) 



[ '■ The page a| local 




done 
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Awesome, right? We can see that the structure is replicated in the JavaScript object, 
and that each action has its own dedicated function as well. Such a function takes as 
many arguments as the route definition has defined for the related action. 

When applying values to this function, we'll get a fresh object that will have the 
URL correctly set along with some other stuff, such as the helpful a j ax one (which 
preconfigures the URL), the method, and so on for dedicated AJAX uses. Thus we're 
getting back the features that helper . form provided for us on the server side! 



Back to our example, we now need our forms to use such JavaScript objects in 
order to deal with the server in an asynchronous way, which will make our 
application a single page one as we'll no longer leave the page when playing 
with a configured dashboard. 

For that, we'll do a quick change in the actions themselves in order to change the 
response to a single text, rather than rendering a full HTML page. 



static public Form<Iteri> itemForm = form( Item, class) j 
public static Result talk I Long chatld) { 

User user = User, find , byld( session ( "email ")) j 

Chat chat = Chat, find .whereU . eq ( "int ernalld" , chatld) . ] oin( " it ems" ) . f indUnique ( ) j 
Forn<Item> boundForm = itemForm . bindFromRequest () j 
if (boundForm,hasErrors()) { 

return badRequest (boundForm. errors AsJson ( ) . t oSt ring ( ) ) \ 

Item item = boundForm , get () j 
item . user = use r j 
chat . items . add ( item) j 

chat . save( ) j 

ret u rn ok( "done " ) j 

// return ok ( views .html , chat^rajjn .render (chat, itemForm, imageForm) ) ; } 



public static Form<Iniage> imageForm = form' Image, class) j 
public static Result receivelmage ( Long chatld) { 
User user = User. find . byld( session ( "email ")) j 

Chat chat = Chat, find .whereC) . eq ( "internalld" , chatld) , j oin( " items" ) , f indUnique () j 
Form<Image> filledForm = imageForm . bindFromRequest ( ) \ 
if(filledForm.hasErrors()) { 

return bad Request (filledForm.errors( ) .toStringf ) ) \ 
> else { 

Http HultipartFormData body; 

body - request ( ) . body ( ) . asHult ipart FormData ( ) \ 

Http MultipartFormData FilePart pic = body . getFilef "pic" ) j 

if ( Image. ImageType . get ( pic . get Content Type( ) ) == null It 
return badRequest (" bad file : " + pic . get Content Type ( ) ) \ 

// return badRequest ( views .html . chat room.render(chat, itemForm, imageFormi); 

} 

Image image = f illedForm . get ( ) j 

image. pic - pic . getFilef ) j 

image . filePat h = pic . get File( ) . get Pat h( ) ; 

image. user = user; 

chat . images. add(image) ; 

chat . save( ) j 

return ok( "image saved"); 

// return ok ( views . html . chat, room . render ( chat , itemForm, imageForm) 1 ; } 
} ™ 




There is also another convenient property that has been created, 
webSocketURL, which will be used in the next chapter. 
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Basically, we've just replaced the calls to Scala templates by simple strings. 

That drove us to the last point, the CoffeeScript files that glue everything together. 
The main thing will essentially be the usage of the JavaScript routers when a form 
is submitted. 

Let's start with the easiest one: the item form that simply posts a message to the server. 

As these forms are now added to the document in dashboard/ index . scala . html, 
and it will add the CoffeeScript file that dynamizes the form in the constructor 
of Dashboard. 



## Forms submission logic 
## 

#memoize the select that enable switching between chat rooms 
@interact Select or = @el . find 1 "#chat Select " 1 ; 

## 

## CHAT ROUTER => JS object that holds the 

## routing info for each configured action 

## 

@chatsRouter = playRouter , cont rollers . Chats 

# Send an aj ax request to post a new message to the selected chat 



$form = $ ■ e . cu r rentTa rget j 
chat = ^interact Select or , val i i 
route = @chatsRouter .talki. chat ) 
route , aj ax 1 

data: $form . serialize! ) , 
success : ( ) - > 

console .log' "message sent"! 
error: (data) ■> 
console . din data i 

alert i "message not sent " + date] 



First of all, we create and initialize a field on Dashboard that will hold a reference to 
the select box, which enables the user to switch between the shown chat instances. 
Then we create and initialize another field that shortcuts the lookup of our router, 
that is, the Chats one. 

After some manipulations with the jQuery part of the form, we called the function 
talk on the reverse router that was created by Play! 2, and we used this function 
by providing a parameter that is expected in the route definition: the chat's ID. The 
result is the object with the a j ax function in it, which we can use to send 
our request. 




false 



That was really easy, thanks to Play! 2, its compiler, and the code generator. 
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For the other form (the image) it's as simple as this one, but we will just need a 
jQuery plugin, which will ease the work to send a form with a file asynchronously. 
For that, I've chosen a good one, which has the advantage to work and to be simple: 
jQuery Form Plugin. You can find it at http : //malsup . com/ jquery/f orm/. 

Download the file and place it in public/javascripts/ along with the already 
present jQuery file, and then go to the main template to load it as well. 

Having this library in the scope, we can go back to our Dashboard class and update 
the constructor with the relevant code to publish the file asynchronously, shown 
as follows: 



#Since a file is involved we need a gljjtjin to do it 

# so this object configures it for our sendlmage form 

# »> http://iquery.malsup.com/ «< 

\W/AWAWW\WvW^ VvVv'vVvVvv 

@upl oadFo rmOpt ions = 
target : '#upload ' . 

success: ( responseText , st at usText , xhr, $f ormj -> console . dir( responseText i 

# send the image and caption asynchronously 
@el . find 1 "#sendlmage" i . submit le! => 

$form = $i. e , current Target i 

chat = ^interact Select or . val 

route = @chatsRcuter . receivelmage 1 chat ) 

$f orm . att r( "action" , route . url ) 

# ! ! ! ! USE THE i query, fan plugin III! 
Iform.ajaxSubmit' @upl oadFo rmOpt ions I 
false 



Quite the same kind of code as the previous one. The only thing that changes is the 
usage of the plugin's function, aj axSubmit, by changing the value of the action 
attribute with the relevant one using the reverse action. 

We're done now; we can now test by chatting in real time using several browsers 
without having to go back each time we submit a new thing. 

Actually, we're missing something— the hardcoded URL when we were polling. So? 
What's the big deal? The only thing we have to do is adapt the JavaScript action to 
declare the contentsince reverse router in Application . j ava, and use it in our 
client-side code— I'll leave it as an exercise. 

We have a very cool chatrum now. But still, there are some things that we could 
do to enhance it, and to fit it better into "the new way of doing the Web". That is, 
the usage of reactive streams rather than several pollers (which we might have to 
aggregate into a single one, but anyway). 
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Real time (advanced) 

The Web has changed; HTML5 is almost there and is already implemented by all 
browsers. At least, the useful parts of it are available, especially the parts we'll use in 
this section. 

It's now very familiar and it won't surprise you anymore, but Play! Framework 2 
will again demonstrate that it is a real web framework by integrating things such as 
WebSocket or its old fallback, Comet. 

Actually, Comet is not really a fallback for WebSocket since it's unidirectional while 
the latter is bidirectional. Nevertheless, there is another specification that does the 
same as Comet: Server-Sent Events (SSE). Even if an implementation of SSE is not 
(yet) provided by default, Play! 2's API will help us a lot in implementing it on our 
own really easily. This tool in hand, our application would have a really good push 
mechanism in place. 

In this chapter, we'll focus on the most popular one, which is WebSocket. Hopefully, 
this is the one we'll need in our application to make it more responsive and reduce its 
consumption in bandwidth and resources (remember the endless loop to poll). 

Adding WebSocket 

WebSocket is a duplex connection between a client and a server that enables 
bidirectional communication, like what we would love to have in our chatrum. 

What we're going to do is enable our client side to listen to server messages in order to 
update the chatrooms that the user has configured in its dashboard. We'll continue in 
this great direction by re-using the connection in order to push the messages as well, in 
a standardized way, using asynchronous tasks, no loops, and without boilerplates! 

Essentially, what will be done is the replacement of the actions talk and 
contentsince by a new single one that deals with WebSocket. 

For this action, Play! 2 requires us to define an action that returns an instance of 
play . mvc . WebSocket<A>. As you can see, it has a generic type, which is the class 
of the expected representation of the messages that are sent to the connection. 

So, first of all, we remove the obsolete actions and create a new one called 
chatsstream. And, of course, we can remove the route definition as well. 
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The following screenshot shows the resulting Chats controller: 







29 


static 


30 




31 


publ ic 


37 


} 


38 




39 


publ ic 


55 


} 


56 




57 


publ ic 


61 


} 


62 




63 


publ ic 


74 


> 


75 




76 


static 


77 




78 


public 


2G3 


> 


204 




205 




206 




207 


public 


208 




209 


public 


233 


} 


234 




235 




236 


} 



static final public Form<Item> itemForm = form( Item, class) .: 



public static Form<Image> imageForm = formC Image, class) ; 



And the following screenshot shows the resulting routes file: 



22 # Chats 

23 GET /form/chat cont rollers , Chats . register-Chat ( ] 



24 GET /chats controllers, 

25 POST /chat controllers, 
GET /chat room controllers, 

Vv'vVv'.VvVvVvV 

POST /chat/ : chat/image controllers, 

28 

29 GET /real/chats/ : ids cont rollers , Chats . chatsSt ream( ids : St ring, t imest amp : Long) 

30 



Chats. all Chat s( ) 
Chats . createCh at ( ] 
Chats. loadChat( ) 
Chats. receivelmagefchat : Long) 



With the noise gone, we can now look at the signature of our new action, 
chatstream, that takes two parameters: 

• chat ids: The chat instances' ID that the user has selected for his/her dashboard 

• t imestamp: The time at which the client will start listening for 
incoming events 

That was the parameter part, and if we look at the result type we'll see what 
we had expected — the WebSocket type, with its generic type org . codehaus . 
j ackson . JsonNode. 
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As WebSocket is a connection wherein streams are involved to transfer bytes, 
commonly represented as strings, one would think that we'll have to slurp the 
messages' content and process them into JSON. But we won't, because Play! 2 knows 
that JSON will be used in 99 percent of use cases. So, everything will be done for us. 
However, they've also prepared the ground for simple strings and bytes. 

So far so good; but before getting into the details of creating such an instance of 
WebSocket dealing with JsonNode, let's have a look at the preliminaries: 



static final public Form<Item> itemForm - f orm ! Item, class) ; 

public static WebSocket <JsonNode> chat sSt ream[ final String chatlds, final Long timestampj { 
final User user = User . find . byld ( session! " email ")) ; 
final List<Long> chatldsList = new ArrayList<Long>{ ) ; 

String!] cis = chatlds . split (",") ; 
for (String c : cis) { 

chatldsList , add ( Long , parseLong ( c) ) ; 

> 

return new WebSocket <JsonNode> i ) { 

// Called when the WebSocket Handshake is done. 

public void onReady ( WebSocket . In<JsonHode> in, final WebSocket . Out <JsonNode> out) { 

// For each event received on the socket , 
in , onMessage( new Callbacks JsonNode> it^ 

} 

)l. 



} 



Our intent is to reduce the amount of traffic on the wire (graceful for mobile 
applications), so we'll have only one connection between the client and the server. 
This single connection will deal with all messages from the client (chatting) and a 
multiplexed wave for all chat updates. 

That's why our action takes a string parameter, which is the list of chat instances' 
IDs list we'll have to listen to for updates. 

- I recommend you to think how we could have done this using 

% \ splat parameters in the routing definition rather than a simple 
r^*^ string that we split explicitly in the action. 

So we process this string to retrieve all IDs in a dedicated list, and we'll keep a 
reference to the connected user too. Then we start creating the real answer, which is 
the implementation of WebSocket itself. 
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As we may have noticed, to create such an instance we'll need to implement a single 
method, that is, onReady. This is the method that will be called when the connection 
will be set and the server will be able to deal with the client. As it's the time when 
communication takes place, onReady accepts two streams as parameters: 

• in: This parameter is an instance of WebSocket . ln<A>. It represents the 
messages' input stream, where the client is pushing messages that must be 
compliant with the generic type A of WebSocket (here JsonNode). 

• out: This parameter is simply the other way around, with a dedicated class 
WebSocket . Out<A>. 

Obviously, we return the inline implementation as the result of our action. 

Having done that, we've already defined a connection between a client and this 
action; really, nothing more has to be done. The internals will manage the persistent 
connections with all connected users. 

Thus, we can now move on to one of the two actions that this action might do, which 
are receiving a message (talk) or publishing events (update). So let's start first with 
the talk use case. 

Receiving messages 

The use case is to take the incoming JSON-encoded messages and persist them as the 
item list of the chat instance. As our socket is unique for each client, the message 
should contain the information about the targeted chatroom. 

Reacting to the incoming message is pretty easy, because of the WebSocket . in<A> 
class that has a method onMessage, which will be called whenever a message arrives. 
Given this semantic, it's fair enough to pass it an argument, which is a callback (a 
command) — so familiar when coming from the JavaScript world. 

Such a callback is simply a Java workaround for a lambda function that will take in 
our case one parameter of type JsonNode. 

Back to our task now, we need a callback that retrieves the information about 
which chat is targeted and what the message is, right before adding it to the 
items list of Chat. 
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return nev WebSocket<JsonNode- i { 

// Called when the WebSocket Handshake is done, 

public void onReady( WebSocket . In<JsonNode> in, final WebSocket . Out <JsonHode> out) { 

// For each event received on the socket, 
in , cnMessage( new Callback<JsonNode>' ) { 
public void invoke ( JsonHode event] { 

Long chatld = event . get ( "chatld" ), getl_ongValue( ) ; 

Chat chat = Chat . find . byldl chatld] ; 

Form-sit em> f = it emFo rm . bind! event i ; 

if ( f , hasErrorst )) { 

Object Node error = Json. newOb] ect ( ) ; 
error , put ( "status" , "error" ) j 
out ,write( error) ; 

} else { 

Item item = f . get ( ) ; 
item , user = user; 
chat .items.add(item) ; 
chat , save( ) ; 

Obj ect Node result = Json. newObj ect (] ; 
result . put ( " st at us " , "success " ) j 

} 

} 

» ; 



Actually, there is nothing really hard to understand here. It's essentially the 
previously created talk action, but rather than having the targeted chat's ID 
available as a parameter of the action, we assumed that it's part of the JSON 
message itself. 

Then we bind (as usual) our form to the current message; here again, we diverged a 
bit by calling bind rather than bindFromRequest, which is obvious because there is 
no request here! What's also interesting is the response sent back to the client, which 
is another JSON object that is created with the current status and then written on the 
out stream. That's how messages are sent to the client. However, we're going to see a 
better example of such a push message. 

Multiplexing events to the browser 

We have reached the last server-side part of the bilateral communication for our 
chatrum. What we have to do now is provide the connected client information about 
which chat instances have been updated and what is updated. 

There are several ways to accomplish this task; the one we'll choose here is probably 
the easiest and has the advantage of smoothly introducing the Akka library. 
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Akka is part of the Typesafe Stack 2 for everything related to distributed, parallel 
computing, and so on. It provides a fast and non-blocking API using what was 
initially an Erlang concept: the Actor Model that is making us rethink the way 
concurrent tasks might be done. 

The killer features are, for instance, that our application's number of simultaneously 
connected users is no longer limited to the number of threads our server can handle. 
In short, J2EE is mainly based on servlets, where each request takes one thread in the 
pool and holds it until it terminates: this is called blocking. 

Even if Akka provides a lot of features, we won't discuss them here (there are plenty 
of emerging books on it, which are worth considering reading conscientiously); 
however, we'll use one of them, that is, the asynchronous recurring task definition 
(a scheduler). 

Indeed, we're going to check the updates through the usage of such an Akka scheduler, 
by asking it to check the database content periodically based on a timestamp. 

Using the item and image's timestamp field, the recurring task will be able to 
know whether they have to be sent or not. What we'll gain here over the previous 
implementation using contentsince is that only events will be transferred over the 
wire when updates have occurred for all chatrooms. 




This is not yet the most efficient way to do it, but I tried to KISS. 
For those interested in a better one, a tip is to use messages and 
actors when items or images are persisted. 



The following screenshot shows how we can define a scheduled task with Akka, 
and how we can use it to send update events to the client: 
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p lid Lie void onKeaoyi weDiocket , in<JsonHode> in, tinii weDiocket . uut< Jsonnode> out i 1 

// For each event received on the socket, 
in . onMessagel new Callback<JsonNode>' i { ^ 
1 

>l ; 

//scheduling part that fetches the "last updates 
Akka. system!) .scheduler! ) .schedule! 

Duration, create! 0, Timellnit . MILLISECONDS) , 

Du rat ion , c r e at e [ 1 , Timellnit . SECONDS ) , 
new Runnable ) i 

//cache the last update date 
Long last Tiniest amp = timestamp; 

public void run! ) { 

//fetch the content since last Timestamp 
LocalTime t = new LocalTime! last Timest amp ) ; 
//holds the potential data sent to the client 
Object Node result = Json, newObj ect [ ) ; 

//tell the client to update something 
result , put ( "update" . "t rue" ] : 

//control the number of message sent to the client 
boolean send = false; 

//check what have been updated for each chat 
// and create the message part of it 
for (Long chat Id : chatldsList) { 

Object Node current = checkChat ( chatld) ; 
if (current != null) { 

//at least one event available 
send = true; 

result , put ( "chat "tchatld, current J ; 

} 

} 

//if something has been set 
if [send) { 

//send == write to the output 

out .write! result J ; 

} 

//update the last checked date | | not always good but OK. , , 
last Timestamp = System. current TimeNillis! ] ; 

} 



In the previous screenshot, there are some key points that are worth discussing. 
So let's discuss them one by one. 
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The very first thing is the call to the system method of play . libs . Akka. This Akka 
utility class is part of Play! Framework 2 and is hiding Akka's configuration part, which 
is handled through a Play! 2 plugin. This plugin helps us configure Akka through some 
properties in our application . conf file. Then comes the Akka class that wraps some 
boilerplate for us and abstracts things such as retrieving an Akka's system. 

In order to keep things simple, let's assume that such a system (ActorSystem) is able 
to manage concurrent, asynchronous, or scheduled blocks. 



So this actor system has a scheduler accessor that itself enables us to schedule a 
Runnable. For that, we need to configure how this task has to be scheduled by giving 
it the information about the delay before the first execution, and the period between 
each execution— both as Duration instances. In our example, we gave a delay of o 
milliseconds and a cadence of l second. 

The last parameter is obviously the task to be performed, being an implementation of 
the traditional Runnable. 

The second thing to notice is the timestamp being cached at each iteration in order to 
apply a valuable filter on items and images. 



Then there is the send flag, which is there to prevent us from flooding the client with 
empty messages. And what will be sent is simply a message holding the information 
about the updates that have been discovered. 

How these events are discovered is part of the implementation of the checkchat 
method (used in the loop). This method is rather straightforward, because it's pretty 
much the same as our previous implementation of the contentsince action. That 
is to say, we retrieve a Chat instance, loop over its items and images, and keep 
only the new ones. The only thing new is that it will only return a non-null object 
if at least one new event has been discovered. The following screenshot shows the 
implementation of the checkchat method: 




It would have been overkill to talk about the plugin mechanism that 
Play! 2 is providing to extend its server capabilities. However, the 
documentation is evolving on this topic. 




This method could induce the loss of some events due to 
some latencies, for instance. But it'll do the job for now. 
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} 

public Object Node checkChat ( Long chat Id) { 

//holds the changes for the current chat 
Object Node current = Json. newObj ect ( ) ; 

//fetch the chat 

Chat chat = Chat . find . byld( chatld) ; 

List<Item> items = chat. it ems; 
List<Image> images = chat. images; 

//thanks to Java . . . 

List<Item> ritems = ney Array List <It em>( ) ; 
List<Image> rimages = new ArrayList<Image>' ) ; 

//that ' s a map . . . 
for (Item i : items) { 

if ( i ,timestamp( ) . isAfter(t ) ) { 
ritems . add( i) ; 

} 

} 

//that's the exact map... on another instance 
for (Image i : images) { 

if ( i ,timestamp( 1 . isAfter(t ) ) { 
rimages . add( i) ; 

J 

} 

//build a message part only when necessary 
if ( ritems . size( ) > || rimages . size( ) > 0) { 
//put the data 

current . put ( "items" , Json. to Json ( ritems) ) ; 
current . put ( "images" , Json. to Json ( rimages) ) ; 
return current; 
} else { 

//no events to send 
return null; 

} 

} 

} 

); 



Nothing more to say... 



Live multichatting 

Now that we're done with the server side, we must adapt our client-side code 
(CoffeeScript and JavaScript) to deal with our new chatstream action instead 
of the old talk and contentSince ones. 

As there will be only one location where the updates will be resolved, the best place 
to put this code is probably in the Dashboard class (in dashboard . coffee). So it will 
have the responsibility of checking all chat instances it is configured with; that's why 
it will now have to keep a reference to all of them. 



Moving to Real-time Web Applications 



Until now, the check and talk implementations were done in the Chatroom class's 
methods f etchcontent and poll — we can remove them both! 

With the code being a bit more clean now, we can have a look at the Dashboard part 
we're interested in: 



class Dashboard 

constructor: (opt) -> 

4 #[...] 

5 

£ NBV field keeping track of the chats being shown 
@chatlds = undefined 

B 

9 = NOW: talking consists in pushing a J^sori message in the socket 

@el .find' "#talk" i .submit (e) => 
11 $form = $' e , current Target i 

12 

13 chat = ^interact Select or .val I 

14 value = { 

chatld : pa rselnt ■ chat i 

16 message: $f o rm , f indi " [ name=messaae] " i , val 1 i 

17 } 

IB @socket . send > JSON, stringifyvaluei i 

19 

20 false 

21 
22 

joinArray: [array, sepj -> 
24 del = "" 

cs = array, reduce Ix, y) -> 
r = x + del + y 
del = sep 
2B x 
29 , "" 

30 

now: () ■> new Date' i .get Time i i 

32 

opened: (chatlds) => 
34 @chatlds = chatlds 

35 

@routeToSt ream = @chatsRout er , chat sSt ream 1 @j oinArray @chat Ids, @now > ' 

^socket = new WebSocket 1 @rout eToSt ream . webSocket URl_i |] 
@socket . onmessage = (msg) -> 
data = $, parse JSON msg , data i 
if 1 data , update i 

rooms = window, chat rum , rooms 
42 #for comprehension on object with filter 

rooms [ c ]. updateChat ■ d , it ems, d, images' for c, d of data when c . mat ch > "chat [ 0-9] + " i 

44 

45 window. Dashboa rd = Dashboard 



The previous screenshot presents the implementation of Dashboard cropped to what 
we're talking about. 

First, we cover the introduction of a new property, chatlds, which will be an array 
of numbers — the chat instances' IDs. They will be necessary when registering to our 
chatStream action. 
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Still in the constructor, we have redefined the talk part by replacing the old form for 
AJAX submission with the creation of a message object, where we drop a property 
pointing to the target chat instance. Recall that the onMessage method of WebSocket 
in the action chatstream expects such a property to get the instance back from 
the database. Then this message is sent over the wire using a new property of 
Dashboard, @socket, which we'll look at in a moment. 

Let's jump to the method of Dashboard named opened, which takes the list of chat 
instances to be tracked and does the following tasks: 

• It stores the list in the dedicated property of Dashboard named ©chatids. 

• It uses chatsRouter, which we have already created earlier (containing the 
reverse JavaScript router). This time, we'll use its new action, chatsstream, 
which takes the list of the chat instances' IDs as a string and the current 
timestamp as a number. 

• On this reverse JavaScript action, we can use the function webSocketURL, 
which computes a specific URL to target our server-side action through a 
WebSocket (for instance, it uses the protocol ws : //). For that, we used the 
standard JavaScript WebSocket constructor. 

• The created WebSocket object has several callbacks that might be configured; 
we're going to use the onmessage one in order to handle the server-side 
events as JSON instances. 

These messages contain all the latest updates for all chatrooms being 
listened to, so we loop over it to update each of them. The update part is the 
responsibility of the related chat room instance, which declared a method 
that accepts new items and images to be shown. 




We used a static reference to the rooms, which is not a good practice; 
but again, it'll be worth considering something like require . j s to 
deal with such use cases. 
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The only thing left to do is slightly adapting the way we were defining the instance 
of Dashboard and those of Chatroom in dashboard/ index . scala.html and 
chatroom . scala . html, respectively. 



index.5cala.html 



48 i 

<a href="@routes . Chats . registerChat () ">Create a new one</a> 

50 </div> 

51 </div 

52 
53 

@defimng( dashboardForm . value) {data => 
@if ( data , isDefined) { 
56 *:diw> 

@defining! data , get . chats) -[ chosenChats => 
^script-* 

var chatlds = |] ; 
$ function ) { 

@chcsenChats . zipWithlndex , mapi chat_and_index => 

chatlds! @chat_and_index ,_2] = @chat_and_index ,_1 , internaUd; 

63 1 

64 // TELL the dashboard whose rooms have been opened 
window, chat rum. dashboard. opened' chatlds) ; 

66 > ) J 

67 </script> 
@chosenChats , map{ c => 

@chat room ( c j 

70 } 

@participatingChats( chosenChats, itemForm, sendlmageForm) 



chatroom. scala.html 



4 
5 

6 <script> 

$• function! i ■{ 

var room = new ChatRoom { 
id: @chat . internalld, 

10 el: $' "#chat room_@chat . internal Id" i 

11 }); 

12 // HACK to have rooms populated in the dial^rum . rooms package 
window, chat rum = window. chat rum || {} 

window, chat rum , rooms = window, chat rum , rooms l| O 
window, chat rum , rooms! "chat " + @chat , internalld] = room 

16 }); 

17 </script.> 

18 

19 <div id="chat room_@chat . internalld"> 



What is done is pretty obvious: at the time the list of chat instances is known, we 
gave the IDs' list to the opened method of the Dashboard instance kept statically 
in a package of our own (chatrum). 

The other part is quite the same, as we only store the chatroom instances in another 
static reference (which is used in the opened method of Dashboard, though). 
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This closes the client-side part of the activation of real-time features to our 
application. We can now open several browsers and chat in several rooms 
in real time, with enhanced performance. 

Note that this is with a delay of a maximum of 1 second due to the 
checking period. But, as mentioned earlier, we could have used 
advanced techniques of Akka and gotten rid of this small latency pretty 
easily. Unfortunately, it would be beyond the scope of this book. 




Summary 

This chapter was really exciting. We've seen how Play! Framework 2 is there for us 
when we have to bring advanced features to the client side. 

We saw how a dynamic list of a single parameter is easily defined and used 
on both sides: client and server. This is thanks to the Form API and the Scala 
template helpers. 

We also took the opportunity to quickly introduce CoffeeScript, which is 
like a beefed-up JavaScript, avoiding a lot of boilerplates or common errors 
with JavaScript. 

With that in mind, it was so easy to poll the server in order to fetch the information 
that must be updated asynchronously on the current view, without requesting any 
actions from the user perspective. 

We enjoyed the way we can have a predictable and checked generation of our URLs 
without having to hardcode anything, even in the CoffeScript world! This has helped 
us a lot in aggregating features in a single component, as we were able to compose 
validated URLs on the client side. 

We finally moved to real time, using WebSocket and Akka. Akka was there to ease 
the definition of recurrent tasks, whereas WebSocket offered a standardized way of 
dealing reactively with clients. We especially noticed how easy it was, thanks to a 
clean and light API that Play! 2 has defined over such difficult use cases. 

Along the way, we built an application, chatrum, that enables the user to configure 
several chatrooms he/ she would like to interact with— in real time. 

This application is still missing a last point to match the standard of today's web 
applications: an open door to the external world using web services offered by third 
parties. We all have the Twitter or Facebook ones in our mind, so let's see how we 
could integrate them into our application in the next chapter. 




Web Services - 
At Your Disposal 

Nowadays, all web applications have to connect with external services. Delegating 
difficult or complex computations to them or interacting on a social network are just 
some examples among thousands. Indeed, this means that our application can focus 
on what it is built for and it will ask other applications for specific needs. 

This leads to the SO A architecture, which is more prone to the separation of 
concerns among services that have a clean and simple definition. A web service is 
one such dedicated service but is available online. In this chapter, we will discuss 
how to integrate a Play! Framework 2 application with such an architecture 
involving web services. 

This kind of distributed architecture can lead to some problems because it relies on 
remote services, which most of the time don't have guaranteed SLAs. So they might 
block the server until a response is given or a timeout has occurred; meanwhile, 
other users who could have sent requests to the server will be queued. 

For such cases, Play! Framework 2 comes with non-blocking helpers that will ease 
the work with long or potentially long tasks. This is mainly based on the underlying 
Akka system. To demonstrate this, we will cover the following points: 

• Get the big picture of the Web Service API 

• Access the Twitter API as a web service serving tweets in the JSON format 

• Update the dashboard to integrate the Twitter Web Service which adds 
external information about the content 

• Explain how to use web services in a reactive fashion, even if they 
are inefficient 
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Accessing third parties 

In this section, we'll see how we can access remote services through HTTP using the 
Web Service API (WS API) that Play! Framework 2 has defined for our use. 

A web service can have several meanings, such as access to certain resources or 
functionalities, but it can also have completely different architectures and data 
representations, where the popular ones are JSON and XML. 

So, integration with such third parties through a simple and common API requires 
quite a lot of abstraction. Hopefully, Play! Framework 2 has prepared the field 
with an API sharing concepts used in controllers' actions, such as body parsers, 
for instance. So it won't take that much effort to understand how we can use it. 

Actually, all that we'll need is a single endpoint for Java and another one for Scala: 

• In Java, the play . libs . ws class declares plenty of static methods dealing 
with web services 

• In Scala, there is the play . api . 1 ibs . ws . ws object, which contains the same 
functions as in Java, but with a Scala flavor 

Indeed, these classes define all of the methods we'll need to interact efficiently with 
our HTTP services. 

ws defines two important classes: WSRequestHolder and Response. 
wsRequestHolder enables multiple request creation and execution of all kinds 
(GET, POST, streams, files, and so on). Response is obviously the opposite, that is, it 
holds the result of our request after processing including the status, data, and so on. 

But in fact, we'll never create any of them because Play! Framework 2 also 
abstracts their usage through the function url in ws. This function is able to create 
WSRequestHolder using the string argument we must pass in, which is the base 
URL. The following screenshot shows the skeleton of the ws class: 
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public class WS { 

private static AsyncHttpClierrt client!) { 
return play, api.libs.ws WS client ( ) ; 

> 

/** 

* Prepare a new request. You can then construct it by chaining calls, 
* 

* flparam url the URL to request 

*/ 

public static WsRequestHolder url I String url) { 
return new WSRequest Holder! url ) j 

} 

/** 

* Provides the bridge between Play and the underlying nimj reguest 
*/ 

public static class WSRequest extends Request Build erBase-=WSRequest> { (^j 

} 

/** 

* provides the User facing API for building WS request, 
»/ 

public static class WSRequest Holder 
} 

/** 

* A WS response . 

*/ 

public static class Response { q 
} 

/** 

* Sign a WS call , 
•/ 

public static interface SignatureCalculator i i^i 
} 



Ok, now what does wsRequestHolder stand for? In simple terms, it provides the 
abstraction over the creation of HTTP requests. 



So, with such an instance of wsRequestHolder, we can prepare the query by setting 
some parameters using setQueryParameter, and give it some authentication 
information using setAuth (and so on for other preparation methods). 
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Having prepared the query, the resulting instance can be sent using methods such as 
get, put, post, delete, head, or option. The methods put and post are overloaded 
several times because they can be assigned with a body content; that's the purpose of 
methods such as put (InputStream body) or post (String body). 

That was for the request part; let's see what's reserved for us by Play! Framework 2 
on the response side. But, before moving to this part, we should take a look at the 
return type of the send methods (get, put, post, and so on): 



/** 

* Perform a PUT on the request asynchronously, 

* Sparam body represented as a File 

*/ 

public Promise<Response> put (File body) { 
return esecuteFile( "PUT" , body); 

> 



In the previous screenshot, which presents one of the put methods available 
to send a body to a web service using the HTTP put method, we can see the 
Promise<Response> result type. 

Promise is a structure that is nowadays more and more popular across languages 
because of its worth in the Web world. For instance, j Query . Deferred is one good 
example a Promise object because of its heavy usage in the jQuery framework. In a 
way, it represents an AJAX call. 

The main purpose of Promise is to create a task that will be processed at some time, 
asynchronously, that is, in a non-blocking way. Actually, it is built upon another 
concept called Future, which is the real asynchronous piece as its name intuitively 
implies. So, the put method is promising the invoker that a Response instance will 
be available. Hence, Play! is able to react in such a way that it will suspend this 
action once the result has arrived. 
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We can now get back to our Response type, which is the generic type of the Promise 
object we've just discussed —which declares that a sent request is promised to get 
some response at some point. 







* A WS response. 


*/ 




public static class Response { 


private com. ning. hrtt p. client. Response ahcResponse; 


publ ic 


Response ( com. ning. hrtt p. client . Response ahcResponse) { p^t 


} 


/** <7T* 
1 (^J 




publ ic 


int get Status! ) { q 


} 


/** 




* Get 


the HTTP status text of the response 


*/ 




publ ic 


String get St at usText ( ) { 


} 






publ ic 


String get Header! String key) { q 


> 






public 


String get Body () i^j 


} 




/**E3 




public 


Document asXml ( ) { f^i 


} 


/** 




public 
} 


JsonNode asJson() { q 


/*• £3 




public 
} 


Input St ream get Body AsSt ream ( ) { f^i 


/** q 




public 


byte[ ] asByteArray ( ) { q 


} 


/** 




public 


URI getUri( ) { q 


} 


} 
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Great! Finally, a response is exactly the same as an action definition; it presents 
methods that are very similar to the ones we've seen up until now. Indeed, the 
highlighted methods are shortcuts that enable us to retrieve the response's body 
(remember, for actions it was the body of the request) that is parsed and represented 
as well-known and traversable structures such as XML, JSON, and so on. 

The amazing hidden feature that is provided in Play! 2 is that the body is handled, 
parsed, and translated in a completely reactive fashion, thanks to the iteratee 
pattern that is used, similar to what was done for the requests' body. 

Now that we've got the overview of the API, we'll look at it in action. For that, we'll 
choose a third-party service and try to integrate it smoothly into our application. 

Let's take Twitter as this third-party service. Twitter exposes an API on top 
of its social network which enables us to do almost everything that we would 
like to do with Twitter, such as tweeting a small message, recovering others 
based on a hashtag, or even searching for new users. Even though most of the 
functions provided by this service require an authentication, others aren't. As the 
implementation of such an authentication protocol (such as OAuth 2) is beyond the 
scope of this book, let's focus on the ones that don't require authentication. 



In this section, we will update the chatrum application to enable some interaction 
with Twitter. What we're going to do is search for tweets based on a hashtag and a 
username. For that, we'll look for items in the chatrum that have special patterns, that 
is, words starting with a hash (#) or an at sign (@). First of all, we'll see how to use 
Twitter to retrieve information using a browser and the API specification. 

The Twitter REST API provides an entry point from which it will be able to do a lot 
of search operations. This entry point is the URL http : / /search . twitter . com/ 
search . j son. At first glance we can guess that the operations will represent the 
response in JSON. 

In order to search on a hashtag, this URL can be set with a search parameter named 
q that holds the hashtag, prefixed by the well-known # character. Of course, the 
request is a GET one. 




There is an amazing Play! add-on (plugin) that eases 
integration with external services, especially for social ones. 
Some information regarding the add-on can be found at 
http : / / securesocial . ws. 



Interacting with Twitter 
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So let's try this in our browser; it will help us later because we'll have the opportunity 
to analyze the output and see what data we can retrieve, where, and how: 



^- OA O search.twitter.com/searchj son?q=%23playf ram ework 



co»pleted_iii : 

■ii id: 26265636QHD16756D0, 
■ax_id_Btr: "262656360304675535", 

neit_page: "7page=24:na>t_i d=262656 36000467 55354q=$23playf ramevork", 
page: 1, 

que r y : " 2 3 c 1 a y f r a~ ewe r it" , 

re£reah_url: "7siiice_id=262 65636DB[H6755B5Sq=*23playfr i" 
- reaulta: 

created_at: "Sun, 23 Oct 2012 20:45:30 +0000", 

fro>_uaer: "z ■: '.'.'.i" , 

fro>_UBe-r_id: -.: 2-.i±Gi~: , 

f ro>_uaer_id_H tr : " 2-zi-.C'l~" , 

f zo>_uae-r_na»e : " 7 1 : . : Ku e 1 !'.a " j 

goo : null, 

id: 262656360804675600, 
id_atr: "262656360304675505", 
i ao_language_code : " c 1 " , 
- metadata: 

re aul t_type : 

prof i le_i»age_ur 1 : ' hz zn : ./ / aO . rwi^g , c o:v'prpf i l&_i:na jb 5/1330392223/ - - 
prof i le_i«age_ur l_httpa : " h::cs : //siO . twimg, coin/prDfilg_iiiiajB5/13333g22 
aource : *■ i 1 - r .= h:=: = i;::: r i". - . r : . *i . . ^ r . c cr. ■' i ju ; . r 4 gi ; web4 1 1 ; / a4 gi ; " , 
text: "*?layS'raiitevcjrk + *3cala + tAkfca + fCof feeScript 4 t kinetic. j 5 = 
ts_uaer: 
ts_uaer_id: '. , 
to_uae r_id_atr: "Z", 
to uaer nus: null 



The previous screenshot shows us how to create a query (note the %23 value before 
the playframework tag) using the Twitter REST API, and it also shows how a 
response is structured (encoded in JSON, as expected). 

The result presents a lot of information that we won't need in our example. 
So we'll only use the results property. This property is a JSON array containing 
all of the tweets matching the query, and with each tweet having a certain amount 
of data. We'll continue to focus on the part we're interested in: the f rom user and 
the text properties. These properties are the username of the tweeter and the 
tweet's text respectively. 
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The search on a particular username is exactly the same but the prefix has to be 
® rather than # in the q parameter; meanwhile, the result has exactly the same 
structure. That's fine, we'll probably be able to share some code. 

Based on that, let's now see how to create an action that will search Twitter and 
return its own representation of the result, so that it will be usable on the client side 
of our application. 

For that, we'll first add a new dedicated controller named Twitter. This controller 
defines two actions: 

• searchTag (string tag) : Searches Twitter for tweets tagged with the 
given tag 

• mentioning (String user) : Searches Twitter for tweets mentioning the 
given username 

However, as said earlier, some logic can be shared, so this controller will have 
another method called f indAndSeek (string q) , which is not an action by itself, 
but will contain the logic for searching on Twitter. 

The following screenshot shows the skeleton of our Twitter controller: 



import static piay. lids, r . ' ; 

import play .libs . Json; 

import org . codehaus , j ackson . *; 

import org. codehaus, j ackson . node.*; 

public class Twitter extends Controller { 

private static final String SEARCHURL = "http://search.twitter.com/search.ison"; 

public static Result sea rchTagi String tag) { 
String q = "#" + tag; 
return f indAndSeek! q, true); 

> 

public static Result mentioning' String user) { 
String q = "@" + user; 
return f indAndSeek! q, false); 

} 

private static Result f indAndSeek ( String q. Boolean isTag) 

I 

I 

The definition at this stage is quite obvious (the logic is hidden). The actions are 
simply calling the third method that contains the logic. As the parameters of 
searchTag and mentioning don't include the Twitter-specific characters, the 
actions are preparing the query before launching the search. 
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Before moving to the web service call, we'll define the route for each action: 



40 


# WS 






41 


GET /ws/tw/taq/ : q 


cont rollers .Twitter 


searchTagt q : St ring] 


42 


GET /ws/tw/mentions/ 

V'.WMWMW.W'MW'M'v 


user cont rollers .Twitter 


mentioning! user: St ring) 



Using the Twitter API 

In the previous section, we set up our actions and routed them; let's now take a 
deeper look at how we can deal with the Twitter REST API— the definition of the 
f indAndSeek method. 

Its implementation will be split into three parts: the call to the Twitter API, the 
transformation of the result's structure into a custom one (adapted to our needs), 
and finally the execution of the whole thing. 

The following screenshot shows the implementation of f indAndSeek: 



private static Result f indAndSeek ( String q. Boolean isTagj { 

// Initialize the search that will get the Twitter Jjson response 
40 // The response is not yet there.., we've only got a PROMISE of it 

Promise<MS. Response; promise = WS. url t SEARCHURL) . set Que ryParamet er ( " q" , q) getll. 

42 

43 //adapt the Twitter Json structure into a custom one, usable in our UI 

Promse<Result> promisedResult = promise. map( 
new Function<WS. Response , Result>( ) { 

public Result a p pi yi WS , Response response) { 
47 // the original Twitter response is Json encoded 

JsonHode json = response . asJsonl J ; 
49 // we're only interested in the results property 

Array Node results = Array Node i ] son . get [" result s ") ; 

51 

52 // Our representation container 

List <Hap<St ring, String» tweets = new ArrayList<Hap<St ring, String»(); 
rterator<JsonNode> it = result s . it e rat o r t) ; 

55 //loop (anjh) on results 

56 while litThasNextl 1 1 { 

JsonNode t = it , next [ ) ; 

Hap<String, String> m = new HashHap<St ring, String>' i: 

59 // retrieve the user name 

m . put ( "user" , t , get [ "f rom_user" ) . asText ( ) ) ; 
61 //retrieve the text 

m. put ( "tweet", t . get [ "text " ) .asTextl ) ) ; 

//save the new object 

tweets , add! m! ; 

65 } 

66 //return an result with OK status 

67 // containing the tweets as Json in its body 
return ok ( Json. to Json (tweet sIXT* 

69 } 

70 } 

71 I J 
72 

73 // ask the promise's result using the get method 

return promisedResult|. get t ) ; 

75 

76 > 
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We're now going to review each part separately. First, we create the request using 
the WS API: 



39 


// Initialize the search that will get the Twitter Jsjsn response 




4G 


// The response is not yet there,., we've only got a PROMISE of it 




41 
42 


Promise<ttS. Response • promise = WS, url [ SEARCHURL) . setOueryParameterl "q" , 


l! . get [ ) ; 



What's being done here? First, we've used the URL from ws to create a 
wsRequestHolder object using the base URL for Twitter's search, which 
we've done before. 

What's still missing at this point is the query parameter that is necessary to specify 
what you want Twitter to search for. In the browser, it was provided as the query 
string parameter q. In this case however, we can simply set this parameter using the 
setQueryParameter method. 

So far, we've defined the URL to the target and the parameter to be used; for our use 
case, the only other thing needed (as we don't need any authentication, for instance) is 
to end the definition by calling get ( ) (one line using the fluent API of ws). 

This will result in a Promise<ws . Response> response, that is, the HTTP GET hasn't 
yet been executed. We've just prepared the whole request, which is now ready to be 
sent. Also, it says that the type of the result will be a ws . Response response, but this 
is not the type of response we need in our interface. What we want is a custom JSON 
representation of the body of this response, as shown in the following screenshot: 
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43 //adapt the Twitter Json structure into a custom one, usable in our UI 

Promise<Result> promisedResult = promise , map ( 
new Function<WS. Response Result >( ] { 

public Result a p pi y I WS. Response response] { 
47 // the original Twitter response is Json encoded 

JsonHode json = response . asJson! ) ; 
49 // we're only interested in the results property 

ArrayNode results = ArrayNode j son . get (" results" ) j 

51 

52 // Our representation container 

List <Hap<St ring, String» tweets - new ArrayList<Hap<String, St ring» i ) 
Iterator<JsonNode> it = results , iterator! ] j 

55 //loop (argh) on results 

while I iOasNext I I 1 { 
JsonHode t = it . next ( ) ; 

Hap<String, String> m - new HashHap<St ring, String>(); 

59 // retrieve the user name 

m . put ( "user" , t . get ( "f rom_user" ) , asText ( J ) ; 
61 //retrieve the text 

m . put ( "tweet " , t . get I "t ext " ) , asText III: 

//save the new object 

tweets , add( ■) ; 

65 } 

//return an result with OK status 

// containing the tweets as Json in its body 

return ok! Json. to Json [tweet sTTT" 

69 } 
7G } 
71 ) ; 



For those who aren't familiar (yet) with deferred computation such as Promise, this 
might look a bit strange. However, it's very simple. 

First, recall that the result of the request is not yet there, but we still want to 
transform it. How can we do this? By using the map method on Promise. 

This map method can be like registering a callback (at least for this particular case) 
on the result of the request. But, where such a callback is meant to be imperative 
(with side effects), a map method of Promise will register a function to be executed 
on the result of the initial request and might adapt it in such a way that the result 
of the whole Promise will change. An example is a process that promises to output 
a result of type String (Promise<String>) , which we'll map on to an integer 
using map that invokes Integer .parselnt. The result won't be an instance of 
Promise<String>, but an instance of Promise<Integer>. 
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Also, the result of this callback should be synchronous; if it 
should be asynchronous as well, we must use f latMap rather 
than map on Promise. Indeed, if we use map with a method 
returning a Promise<T> result type, we'll get a result of type 
Promise<Promise<T>>. In short, what we'll do with f latMap 
is get rid of the second Promise object, that is, it will flatten the 
result type. Talking about the real sense of map would require 
much more time and effort than it's worth. However, if you're 
interested in the underlying concepts, I'd recommend you learn 
about Functors. 

The callback we have registered is a function (does that remind you a bit 
of AJAX?), in which Play! Framework 2 (Java) is an instance of the play, 
libs . F . Function<A, B> interface. This type enables us to define an execution 
logic that takes A as a parameter and returns B (well, a function from A to B...). 

Our callback must take the result of the WS API call we have used, that is, 
Promise<ws . Response >, and we would like to set the action result, an 
instance of Result. 

The cool thing now is to check the result type of this map application; it's still a 
Promise but the expected type is no longer ws . Response, but Result. Indeed, 
the Result type traversed the applications of get ( ) and map, and is now a 
type-checked promise. 

The implementation of Function itself is only a transformation between the Twitter's 
JSON structure to our custom one. However, the following statement should get our 
attention for a moment: 

JsonNode j son = response . as Json () ; 

This statement is very similar to a request body's usage we had in actions. 

For the following section, it's worth understanding the shape of the constructed 
custom representation of the tweets. The way to do this is to test one of them in our 
browser. But before that, let's end the code review by covering the very last part of it: 



// ask the promise's result using the get method 
return promisedResult|, get ( J j 

75 
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A single line and its comment that says: take the instance of Promise<Result>, 
get the value in it, and return that value. However, what we did using get ( ) is 
we asked the thread to block until Twitter answers (followed by the handle of the 
body as JSON and the transformation to the target's structure). That's bad! Where is 
the non-blocking feature of Play! 2 in this case? Actually, it's our fault, and will be 
covered in the next section. 



Integrating chatrum with Twitter search 

Now that we have implemented our actions, let's see them working in the browser. 
The following screenshot shows a search for mentions of the username ©noootsab: 



^ Cf It I O localhost:9000/ws/tw/mentions/noootsab| 



: 

- ( 



tweet: 

"RT '^r.oootsab: "rm -rf /" ir, "iNeo^J with cypher 

"start n=node(*) natch r-!r~-[) where r,ot [ IE [rj =Z) delete r.,r nn 

user : 11 locisina" 



tweet: 

" RT Gnoootsab: 3TW,. I'd like to find by myself t some reviewers for my Play! 2 book. 
I'd be so glad if you ping me (@packtpub has awards) . @playf ramework" 



■: 



user: "arexocorjsulting" 



twe e t : 

"?.- ^r.oootsab: About to release my 6th chapter about Play! Framework 2. 
had great time with "WebSocket ir. this or.e : -P . Aplayf ramework" 

user : "arexocor.s'jlt ir.g" 



tweet: 

"RT @noootsab : scalalab - A Matlab like environment for #3cala 
http : / / t. co/zPsWvyi^ > > #wbynot" 



user: "coder weekly" 
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In the previous screenshot, we can see a rendered JSON. This is not 
a part of the Play! Framework 2, but the browser itself might be 
able to discover the content type and adapt its display. 



The simplest form we can have is to represent a list of tweets for which we only want 
to retain the tweeter's name and the tweet itself. 

Everything is in place now to have our chatrum integrated with Twitter searches. 
Actually, the server is now ready, but the client side needs to be updated too. 

So the way we are going to integrate them is via the items that are shown in the 
chatrooms. These items could contain usernames (words preceded by @) or tags 
(words preceded by #). That's our entry point; we'll then parse the items in order and 
add markers, which enables them to be searchable on Twitter through simple clicks on 
them. Finally, the resulting tweets will be printed in a dedicated part of the page. 

First we look at the items, which are rendered not only on the server side but also on 
the client side, and then we'll manipulate the messages to wrap the relevant words in 
HTML spans. 

Remember that when we're loading a chat instance, the items are not only dumped 
into the HTML result by rendering the chatroom template, list Item, scala .html, 
but they are also serialized on the WebSocket during the use of the chat, that is, in 
the chatroom. coffee file. Therefore, here is what we'll do. We'll take the message 
text out and preprocess it to find words starting with @ or #. 

I chatroom. coffee x / listltem.scala.html x \ twitter, coffee X Appl 

@( item : Item) 

2 

<li class="item"> 

4 

-span c"lass="time":=-[ @item .timestamp] </span>  

<span=-@if ( item . user !=nuH ) {@item . user . email }<, span>  >  

@it em . message . split ( " ").map{ w => 



8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 



@if(v(0) == '#'){ 



span class="tag">@w</span > 

J 

@it(v(o) == '@':k 



span cl ass=" merit ion ">@w<. ' span ■ 

} 

@if (w(0) != '#' w(0) != ' @' H 
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The previous screenshot shows the new list item, scala .html template that splits the 
item's message into words and then processes them all, based on their first character. 
Note that we have also added a dedicated class for each type: mention and tag. 

Look at how the first character of a string can be accessed using T 
parenthesis and the index. In Scala, a string is viewed as a sequence I 
of characters, so we can use the access method of the sequence. I 



That was the easy part; the server side using Scala. Now let's see how to do it 
in CoffeeScript: 



2 
6 
7 
1G 
11 
16 


class Chat Room 

constructor: ( conf ) ■ > i^i 

f o r mat Tim est amp : (tsj ■ > i^i 

updateList: (target, list, format i =>i^) 


17 


#format a word ' m ' wrapping in a span having the provided 


class 


cl' 


IS 


formatWord: (m, cl ) => ' <span cl ass= " ' +cl + ' " > ' +m+ ' </span> ' 






19 


#format a word with a class 'mention' 






20 


f ormatMention : (m) => @f ormatWord' m, "mention" 1 








#format a word with a class 'tag' 








format Tag: (m) => @f ormatWord' m, "tag"' 








tfshows all items and images 






24 


updateChat: (items, images I => 






25 


/first update the list of items 






26 


# each item will be pre-processed by splitting the message 






# the resulting words will be checked against the @ anc 


# 






# presence, If so there formatted accordingly and then 


j oined 


back 




@updatel_ist 1 








@el , find' " , react , past " i , 








it ems , 








(i) => 








# this is the item formatting function 








#first we split 








words = l . message . split ■ As+/ ' 








#then we construct a new array with pre-processed words 






message = words, map (wl => 








if w. char At 1 0<=="@" 






39 


^format Mention w 






40 


else if w, char At • 0i=="#" 






41 


@f ormatTag' wi 






42 


else w 






43 


# we ] oin the whole thing back 






44 
45 


message = message ,] oin 1 ' 






46 


result = '<span class="time">[ ' + fflformatTimestamp- 

VvWvWvVvWvWV'A'vV 


l .timestamp ^ + ' 


47 


# we add the pre-processed message 








result += message 

) 
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It might seem far more difficult, but it's not; we've just defined several functions that 
have clean and clear responsibilities, such as formatting a word based on the type 
and the class to add. We could have also pushed the limit further by adding the 
wrapping element's tag name to the argument list. 

Indeed, we're essentially doing the same thing as in list Item, seal a .html: splitting 
the message and formatting each word. The only real difference is the j oin usage; 
that's because the template system is doing it behind the scenes for us. 

With a bit of formatting for classes mention and tag, we can get the result shown 
as follows: 



Welcome o 

O fi O localhost:9000/dashbQard/open 



Connected as thief@hood.com 

Change Chars or create 



So far., 



Talk, it's only talk 

Attached Image 



[12:43:55.728] Ihid@lmw3.com> yeah 
[12:43:55.745] me@liorae.org > true 
[12:43:55.746] thief@ hood. com > indeed 
[17:52:17.65] me@liorae.org > hello. I'm (IT 
[17:52:23.241] thief@hood.com > In n " 
[17:52:36.252] thief@liood.com > So how is#playtramework '.' 



Welcome on Play! 2 -Ov 

C A localhost:9000/d 



Connected as me@home.org 

Change Chars or create 



News.. 



Talk, it's only talk * React 



message 

|so how is tfplayfram 



Attach an i: 
caption 



V Computed Style 



Talk, it's only 


So far... 




Atta 


■ [12:43:55.728] thief@hood.com > yeah 






* [12:43:55.745] me@home.org > true 






• [12:43:55.746] tliief@hood.com > indeed 






• [17:52:17.65] me@liome.org > hello. I'm fa 


noootsab 




• [1 7:52:23.241 ] thief@hood.com > hi man 






• [17:52:36.252] tlnef@hood.com > So how 


s #play framework ? 





News.. 



Talk, it's only talk * React 



hello. I'm @noootsab 
Maximum length: 140 
Required 



| send | 
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Cool but useless at this stage; we need to add some interaction to it. As it's pure 
CoffeeScript that uses everything we've seen so far, we'll just see what the result 
could be: 



• Badino75 » #p lay framework #springiTivc. 1 just voted on "Top 20 Web Frameworks for the JVM". Try il for yourself now at: http:/ , t.eo/4QnqrTPp 

* PeterHilton» One conference, two presentations: £playfraraework and project management - h Hp :/;' t. c o/P 19 1 1 r K d 

» aimluck_iwasaki»Play Framework2.0T'SSL{^S> J 7tll"iit, apache/ngiiLx£S^£&U£LHj t £eU , ^T, £f \^t)'-fM^Zh%,ti i ~th^. #playframework http:,Vl.co/KQrlKLHk 

» Igueye » RT @cestpasdur: Plus je connais ^playframework #scala, et plus j'airae #rubyonrails, tous les concepts £REST y soul, la matnrile en +++ #play2 #penible 

♦ bverbeken » RT @steve_objectify: New blog post - "Functional tests in Play! 2 with REST-assured" http:;Vt. c o-lk] ni 1 22 5 #playframew ork 

* jcsirot » Play Framework Plugin for i^etBeans IDE https: >t.co/Cd3Mt93z (part I ) https: /T.co/gVFnOt2 (pan 2 ) ^plsy framework 

• mguillermin RT (fl:stcvc_objectify: New blog post - "Fniictional tests in Play! 2 with REST-assured" http://t.co/lk]ml225 £pl ay framework 

♦ k33g_org» RT @steve objectify: New blog post - "Functional tests in Play! 2 with REST-assured" http:/yt.cQ/lkIml225 #p lay framework 
" loie_d » RT @steve_objectify: New blog post - "Functional tests in Play! 2 with REST-assured" http:-T.co- lklml225 ^p lay framework 
» mbknor » RT fg stevc objectify' New blog post - "Functional tests in Play! 2 with REST-assured" http:/.'t.co.aaiWFGKz £playframework 

♦ dagb » RT in yassalsundman: Nice w rite-up on using #scala, ^twitterboolstrap. ^plsyframework and #heroku http;. , yi..co. ,l pd31p6LS 

• danielsundman » RT (a:yassalsundman: Nice write-up on using #scala, #twitterbootslrap. £playframework and pheroku http: T.co-pd3lpOLS 

* jblemee » RT @steve objectify: New blog post - "Functional tests in Play! 2 with REST-assured" http://t.co/lklml225 #playframework 

* fXzo » RT [li)steve_objeclify: New blog post - "Functional tests in Play! 2 with REST-assured" http:y'y'l.co'lkHLDxOO ^play framework 

• mandnbian » RT (if steve objectify: New blog post - "Functional tests in Play! 2 with REST-assured" http;//t.co/lklm 1 225 £playframework 



* [18:01:24.241] thieffiihood.com > indeed 




• [18:1:54.907] meffi 1 home, org > ] like#playframework 




• [18:2:1 0.845] Ihieffa 1 hood. com > It's an ^obsession ? i 




• [lS:2;l8.9b3]me@home.org>Yeahkindof j 






News... 


TalK, it's only talk » React 


Attach an image 


message 


caption 


|lt'£ an ffoDsQ5slori ? 




Maximum length: 140 


Maximum length: 140 


Required 





This was done using only the JavaScript router to hit the actions mentioning and 
searchTag and a bit of jQuery to provide a panel where tweets are shown. This 
happens when one of the spans is clicked. For more, you can refer to the code files 
of the book for an example. 

So far so good; we have achieved an easy and straightforward use of a third-party 
service such as Twitter with no pain, no response parsing, request handling, and 
so on. 

But there is still an enormous problem: we've lost the non-blocking features that Play! 
Framework 2 brings. That's because we were waiting for the Promise object to return 
before continuing (remember the return promisedResult . get ( ) ; instruction?). 

However, as mentioned earlier, that's our fault. We didn't use the WS API as 
recommended, and that's the point of discussion for the next section. 
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Long tasks won't block 

In this section, we'll improve the behavior of our application while using 
functionalities provided by third parties (like the one used so far, Twitter). 
Such services aren't always very efficient or may encounter some problems 
or maintenance. 

The problem with that is its independence from our code, we don't have any control. 
While they help us for some parts of our application, these third parties can also 
break our performance. This impact comes from the fact that we're using them in 
actions that have to wait for an external request to respond or to fail with a timeout. 

In such cases, our server can become stuck really quickly by waiting on a large 
number of third-party requests to release. But thinking further, we should be 
wondering why those actions are blocking our threads and preventing other 
requests being handled by the server? This makes no sense; the action, which is 
under the covers waiting for a remote procedure to end, should release the thread 
and wake up at some later point, that is, when the procedure has ended. 

Actually, Play! Framework 2 is meant to work with a very small thread pool 
(usually the number of cores plus one), and that's why our server will slow down 
very quickly. But actually, it should slow very quickly in any case if we think that a 
request is always handled by a thread. 

However, this is not how things are going on in Play! 2. Roughly speaking, the 
framework uses a loop to handle all requests where some can be inactive until 
background operations have been released. This loop iterates each time a thread 
is freed by another process. 

So how can those threads be freed if the action hasn't finished yet? That's the point 
where the Promises come back. Let's have a quick overview on how it's done. 

An action is a static method that returns a Result that will cause an HTTP response 
by the framework. Ok, but Result has a derived class, AsyncResult, which wraps 
Promise<Result> in it. This is the key point. When an action returns such a result, it 
has finished its process, or at least it has prepared it for a future result. As the method 
has returned, the thread can be freed up and made available, which means a new 
iteration that can take the next request or the next woken one. This is non-blocking! 
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Wow! That was intense. Let's now see how to create and return such an AsyncResult. 
In this case, Play! Framework 2 will also hide a lot of things for us, simplifying things. 
In order to create an AsyncResult object, we need to do the following: 

• Create an instance of Promise<Result> 

• Use async (Java) or Async (Scala) 

Nothing else. What more could we ask for? Let's see how we can apply this in our 
Twitter controller: 



38 


private static Result f indAndSeek [ St ring q, Boolean isTagj { 




39 


// Initialize the search that will get the Twitter Js_on response 




40 


// The response is not yet there,,, we've only got a PROMISE of it 




41 


Promisees. Responses promise = WS, url [ SEARCHURL) , set Que ryPa ramet e r ! 


'q" , q) , get ( ) ; 


42 






43 


//adapt the Twitter Json structure into a custom one, usable in our 


UI 


44 


PromisedResult > promisedResult = promise , map ( q 

) ; 




71 




72 






73 






74 


// ask the promise's result using the get method 

VvVvW/AWAW 




75 




76 


//BLOCKING = > 




77 


//return promisedResult .get(); 




78 






79 


// NON BLOCKING 




8Q 


return async( promisedResult ) ; 




81 


} 











The only thing we had to do is to pass promisedResult to the async method, given 
that it's already Promise<Result>. We didn't even have to change the return type! 

Now the Scala version (yes, we had put it aside for a while, but the code files include 
this version as well) is shown as follows: 



def f indAndSeek! q : St ring, isTag : Bool ean ) = Async /*NON BLOCKING */ { 



val promise = WS. url ( SEARCHURL) .wit hQuerySt ring( "q" -> qJ.getU 
val promisedResult =promise , map{ resp => t F^i 

37 } 
3B } 
39 

40 // BLOCKING 

41 //promisedResult . avait . get 
42 

43 

44 promisedResult// BLOCKING . await . get 



45 } 
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In the Scala version, we had to replace await . get with the variable itself. But we 
also passed the whole body of the function to the Async construct when we could 
have just wrapped promiseResult only. 

Reloading our application and clicking on a username or a tag will leave the 
application unchanged at the user level. In fact, it turns out that these asynchronous 
functionalities can be used for any type of long running task and not only for 
web service calls. Indeed, a statistical call to a database can be time and resource 
consuming, so it would be worth defining such requests as asynchronous too. (Note 
that if, for instance, the database's driver is blocking, the request will block at the time 
the data starts arriving.) 

Summary 

In this chapter, we learned that Play! Framework 2 provides all the tools needed 
in order to work with remote third-party services. They represent their data either 
as XML or JSON, but it's not a big deal, thanks to the body parsing feature of Play! 
Framework 2. 

We also took the opportunity to look at the WS API itself, the types that are 
important, and how and in which situations to use them (GET, POST, and so on). 
We're now ready to use any REST API easily. 

Finally, we've seen what an asynchronous request in Play! Framework 2 is, and 
how to create it for long or potentially long tasks. It resulted in the performance 
of the application no longer being directly linked with the performance of remote 
third parties. 

We ended up with a good overview of what Play! Framework 2 is able to offer us 
for the creation of amazing web applications, and how it is integrated with all layers 
composing a modern application, including not only the server side but also the 
client side. 

However, what about the quality of the produced code or the exposed features? 
Are things also going to go so nicely when trying to test such fully-fledged web 
applications? We'll see in the next chapter that the answer to the second question is 
definitively "Yes", and that everything is in place to help us answer the first one. 




Smashing All Test Layers 

A software development stack that does not include testing, in the age of test-driven 
development (TDD), is like shooting itself in the foot. A web framework that is 
involved transversally with the runtime environment should especially enable 
the developer to assert all phases of his/her work - from core logic to an HTML 
presentation through business logic. 

Thankfully, Play! Framework 2 is a very good web framework. It provides plenty of 
helpers to test all those layers. Those helpers will be helpful not only in unit testing 
but also in applicative tests (business) or functional ones (UI, REST, and so on). 

Even though Play! 2 can be integrated with either the Java or Scala testing 
frameworks, in this book we'll focus on Scala testing for both Java and Scala 
applications. That's because testing is a perfect way to start learning Scala, resulting 
in the fact that a test code need not be highly efficient by essence and shouldn't 
include any core logic at all. In short, its implementation is not critical and shouldn't 
be visible to final users. 

A last note before going into much detail, for those who have used the first version of 
the Play! Framework; at the time writing, the way to execute tests has changed a lot. 
Indeed, in the first version, we were able to launch tests through a dedicated URL 
while running the application in DEV mode and we were presented with an HTML 
page where tests could be run by clicking an item. This feature hasn't been recovered 
yet in this second version. We'll see in the next sections how things are going now. 
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In this chapter we will: 

• Start with the easiest tests to write the atomic ones 

• See how to use the test framework that Play! 2 has included, that is, specs2 

• Use the console to run them and interpret the results 

• Perform complex tests that use other components that the application needs 
such as applicative tests 

• See workflow tests that are meant to test features a web application is 
supposed to provide to the outside world (client, browsers, and so on) 

Testing atomically 

A web application is built on several layers, each of them having their own 
responsibilities, such as storage, transport, or business. That's probably why 
it's so difficult to test an application like this as a whole. 

Indeed, most of the time a unit test, or what could be considered as a unit piece of 
the software, will require boilerplates or mock-ups to run it. 

The perfect example is fetching a user's information using the REST API our 
application is exposing. This will require us to have a database, an HTTP broker, and 
so on. But still it should be considered as a unit test. No business logic, no specific 
requirements, just a GET method using an ID. 

That's why in a web application there exist tests that I'm calling atomic. These 
tests don't require a specific environment to be run and, of course, are the simplest 
tests - they can be seen as plain unit tests in a utility library, for instance. 
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A famous testing framework in Scala is specs2. specs2 has an amazing number of 
features that shall require a full book and, actually, the user guide is already one in 
itself (http : / / etorreborre . github . com/ specs2 /guide/org . specs2 .UserGuide . 
html). However, we'll see some of them in action in the following sections. 

The principle that resides within specs2 is the definition of specifications, which are 
kind-of readable sentences that describe the tests you're performing and allow you to 
both define unit as well as acceptance tests. 

Roughly, a specification is structured as several layers. The first layer defines the goal 
of the specification. Then it will contain several fragments that include the test code 
and return a Result class — a specs2 one — such as a standard status (ok, failure, 
and SO on) or a matcher (such as something must be not null). 

specs2 also has two different notations for defining tests, which are the unit and the 
acceptance notations. We'll use the unit one for the rest of the book because it offers 
the more intuitive DSL. 

So let's write an atomic test for our comparison code (back to Chapter 2, 
Scala - Taking the First Step) between Java and Scala. But let's test the Java 
implementation only in Scala! 

What we'll test are the high-order functions that were created in order to draw 
some parallelism between Java and Scala. These are gathered in the comparison . 
Sequence . j ava file. 

The root folder, where the tests files are expected to be in Play! 2, is test, right under 
the root of the application; that is, sibling to app. 

So in order to write our tests, we'll create a folder in tests/atomic and a file named 
ComparisonTest . scala. 
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Here is how simple tests would look and how we can run them: 



ComparisonTests.scala X 



1 package atomic 

2 

import o rg , specs2. mutable ,_ 

4 

5 import play . api ,t est ,_ 

import play . api ,t est , Helpers ._ 

7 

import comparison . {Sequence} 

9 

IB import seal a . coll ect ion . JavaConversions ._ 
11 import seal a . coll ect ion . JavaConvert ers ._ 

12 

If: import j ava . ut il , Ar rayList 

14 

15 //base class => Specification 

15 class ComparisonSpec extends Specification { 

17 // start a logically grouped specs 

18 "Sequence " should { 

19 // test a particular use case 

2G "return even integers using 'even'" in { 

val I = Sequence . even .toList 

22 I must be_==tl_istt2 J 4)) 

23 > 

24 // and another one 

"contain all squares using ' squaredSeq ' " in { 
val I = Sequence . squaredSeq .toList 

27 // ! ! ! Fails ! ! ! 

28 I must be_==(List(l,Q, 4, 9, 16, 25)) 

29 > 

"return even integers using 'even' (list independent)" in i 
val I = Sequence . even .toList 

32 // all elements are even ! not matter if the inner List changes 

I must haveAHElementsLike {case i => (i^.2) must be_==CO)} 

34 } 

"return something when using J v fetch3; " in { 

val three = Sequence , fetch3 
37 // 3 can be found 

( (three . isDefined : Boolean) must beTrue) and 
39 //and get it from option von't throw "None. get" 

(three. get must not throwA(new NoSuchElementExceptiont ) ) ) 

41 } 

"return false when using ' biggerThanS' ' " in { 
val big: Boolean = Sequence , biggerThanS 

44 //none of the list's elements is bigger than 5 

big must beFalse 

46 } 

47 } 



In the previous screenshot, we can see several tests of the comparison . Sequence 
functions we've implemented in Chapter 2, Scala - Taking the First Step. We have at 
least one test by function. 

It should be worth reviewing it a bit now before seeing them run. 

First of all, a specification has to extend the org . specs2 . mutable . Specification 
class, which expects in its body the definition of at least one specification. Such a 
definition must start with a string message declaring the topic of the specification; 
in this case, we test Sequence. This message will be used to give an intuitive print of 
the tests in the console. 
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Some would wonder, how is that possible? Actually, in Scala, monkey 
patching is available using lexically scoped implicit conversions. Thus, 
specs2 has patched the String class with new composition operators. 



Having defined the topic, we have to declare what this topic should respect. That's 
the role of the following fragments that have been introduced using the should 
method on the "topic". In most cases, a fragment is some information separated 
by the in method, a human-readable description of the message (one line) and the 
testing block. Looking at the sample, we can see that those couples can be chained in 
order to create several fragments to be checked all in one row. 

So far so good, but what are those blocks defining how we can create some assertions? 
For this, we need to review the testing blocks. Let's do it one by one, since they're 
using different matchers. A matcher in specs2 can be seen as assertThat in JUnit 
so that it can construct a complex check but also be composed. There are plenty 
of different matchers provided by the specs2 framework and others provided by 
the Play! Framework 2 as well (we'll see them in the following sections). There are 
five fragments being defined in the sample shown in the previous screenshot. As 
mentioned before, each of them return Results (of which matcher is a subtype). 

The key point is the must method that can be used on any computation. This 
method's role is to take a predicate to assert the correctness of the computed value. 



OK, this time we can see how to do some checks. The first check for the even 
function, which returns all even numbers in the Sequence list, is asserting that the 
resulting list will exactly match the expected one. For that we take the result of the 
computation and say that it must be identical to the provided expected List of 2 and 
4. An equality comparison is done using the be_== operator. You guessed it; there 
are other such comparators such as be_<= and so on. 




This is possible using the monkey patching trick we saw previously 
(for String). For your information, Scala has a dedicated term for 
this technique called pimp-my-library. 




We imported the Java conversion methods in the beginning of the 
class, so we're able to ask toList on the j ava . util . List that 
returns the even function. 
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Moving to the second test (fragment), we checked that the result of squaring 
each element in the list is equal to the provided List of squares. This is cool, but 
hardcoded. Even if the comparison code is using the same List instance all the time, 
in the real world those functions must work on any List instance. So we would like 
to assert that the function is respecting its contract; for instance, the even function 
execution must always return a List that is composed of even numbers only. This is 
shown in the third test wherein we asked the result to have all elements respecting 
the provided pattern. In this case, the pattern is simply the item itself (which is 
inferred to be an int), but it must be a multiple of 2. 

The fourth test is a bit more advanced (OK, not that much) because its result involves 
a conjunction of two assertions, one of them being a simple Boolean check using the 
beTrue operator. The second is the negation (using not) of an unsafe result (that 
throws a NoSuchElementException). For this last point, it'd be worth noting that 
None that is extending Option<A>, the result type of find, is throwing an exception 
when trying to get the underlying value. 

And finally, the last check is simply asserting a false result. 

That was easy. Our tests have been written; let's see now how we can run them. 

Running our atomic tests 

In this second version of the Play! Framework, the test environment configuration 
and their runs have been delegated to the build tool SBT. Hence, to run the tests 
we must enter the play console, and rather than launching the run command, we 
can execute the test command. This command has the responsibility to compile 
everything, including the sources in the test folder, and then run all tests in there. 

Here is the result for our tests. 



[play-jbook] $ test 
[info] ConparisondSpec 
[info] 

[info] Sequence should 

[info] + return even integers using 'even' 

[ ] x contain all squares using 'squaredSeq' 

[ ] '2.6, 4.0, 8.B, 16. B, 32. B' is not equal to '1.6, 4.3, 9.B, 16. B, 25. O 1 (ConparisonTests . scala : 28) 

[ ] Expected: [1].B..., [9]. 8..., [25]. 9 

[ ] Actual: [2], 9..., [B].Q..., [32], 

[info] 

[info] return even integers using 'even 1 (list independent) 

[info] return something when using 'fetch3' 

[info] + return false when using 1 biggerThanS 1 1 

[info] 

[info] 

[info] Total for specification ComparisondSpec 

[info] Finished in 50 ns 

[info] 5 examples, 1 failure, 9 error 

[info] 

[ ] Failed: : Total 5, Failed 1, Errors B, Passed 4, Skipped 9 

[ ] Failed tests: 

[ ] atonic. ConparisondSpec 

[ ] {f ile:/home/noootsab/sr<:/book/play-]book/}play- jbook/test: : Tests unsuccessful 

[ ] Total tine: 1 s, conpleted Nov 6, 2912 7:29:56 AM 
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Wow, what are those errors, crosses, and scary messages shown there? Actually, 
that's why tests are written, to discover mistakes. And this is the result we'll get 
when mistakes are found. The result of the tests shown here is telling us that four 
tests out of five were successful, so one has failed. Finding which one is pretty easy 
since it's the only one in the tests summary that has an orange cross whereas the 
others have beautiful green plus signs. 

Before looking at the failure, we shall take a look at what's being printed by the 
framework on the console. 

Indeed, since we respected the structure and the text content, for which we've been 
helped by the DSL (Domain Specific Language) itself (using methods named should, 
in, must, and so on), we can now take the output and read it from the top; line by 
line it provides the following output: 

• Sequence should return even integers using even 

• Sequence contains all squares using squareSeq 

These sentences simply describe what the test will do. 

Back to the test that has failed; we notice that the framework is literally telling us that 
the result list (printed first) isn't equal to the expected list (printed later). 

Then it prints the list again with their role in the test and where they differ. 

So it seems our squareSeq function is buggy (it's true); here it is: 



90 


/*map*/ 


91 


public static <B> List<B> map 1 Functionl<Integer, B> f) { 


92 


List<B> result = new ArrayList<B>[ ) j 


93 


for (Integer i : list) { 


94 


result ,add(f.apply!i) ) ; 


95 


} 


96 


return result; 


97 


} 


98 


//233 chars 


99 


public static List<Double> squa redSeq ! ) { 


100 


return maptnew Functionl<Irrteger, Doubles- ( ) { 


101 


public Double apply i Integer element) { 


102 


return Math,pow(2, element); 


103 


} 


104 


}); 


105 


} 



See? Indeed, rather than computing the square of each element, we computed the 
nth power of two of element, which can be checked easily since the test's result has 
printed the actual List containing values such as l (20), 2 (21), 4 (22), 8 (23), 

16 (24),and 32 (25). 
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The fix is rather trivial; just swapping the arguments will do the trick. After that 
change, running the tests again will result in the following screenshot: 



[play-jbook] S test 

[Info] Compiling 1 Java source to /home/noootsab/src/book/play- jbook/target/scala-2.9.1/classes. . * 

[Info] Compiling 1 Scala source to /home/noootsab/src/book/play- jbook/target/scala-2*9,l/test-classes. . . 

[info] ConparisonSpec 
[info] 

[info] Sequence should 

[info] return even integers using 'even 1 

[info] + contain all squares using 'squaredSeq 1 

[info] return even integers using 'even' (list independent) 

[info] + return something when using 'fetch3' 

[info] + return false when using 'biggerThanS' 1 

[info] 

[info] 

[info] Total for specification ConparisonSpec 

[info] Finished in 61 pis 

[info] 5 examples, failure, error 

[info] 

[info] Passed: : Total 5, Failed 0, Errors B, Passed 5, Skipped 
[success] Total tine: 3 s, completed Nov 6, 2912 4:59:14 PM 



No more red! 

That was a lot of fun, but atomic tests are not the only tests we need while creating 
a web application. Most of the time actually, they're in the minority. Because of the 
architecture of a web application, we mostly need tests that involve the server itself, 
or at least a part of it. 

In the Play! Framework 2, the main component at runtime is the Application 
singleton itself, which is a piece of software that can do everything unless it is 
working as an HTTP server. 

Nevertheless, this is very common because we'll be able to test artifacts such 
as controllers. 



Writing applicative tests 

When testing a web application, we quickly come upon the problem of setting 
up a rather complete environment. This environment is meant to contain enough 
information needed by business workflows. Such unit tests reach the limits of atomic 
tests and thus can be considered applicative. 

Such an environment can be complex because, most of the time, it involves a 
database or an application context with components such as caching. This task 
can be cumbersome in other frameworks because they either don't provide the 
whole stack, like Play! Framework 2 does, or they require several actions (new 
dependencies, annotations, project-specific configuration, dedicated test runner, 
and so on) to be implemented. 
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In Play! 2, applicative tests are handled by the framework itself through the 
definition of a bunch of helpers and mock-ups. 

The key point will be the Application class, which is responsible for setting up the 
context of the web application. Indeed, an Application instance is created at the 
very start of a Play! 2 application. It will also configure third-party tools based on 
the application . conf file content. In a sense, it's able to simulate everything, even 
the HTTP server itself. Actually, it won't accept HTTP requests but it will accept 
simulated ones. 

Examples of what will be configured are the database connection provider, the cache 
system, the routing component, and so on. 

What we end up with, with this Application in hand, is the ability to test our 
Controllers or templates, or even the routes themselves. However, what we won't 
be able to do at this stage is test remote functionalities such as HTTP requests served 
by a real web server. 

As said previously, Play! Framework 2 provides a good set of tools in order to start 
or simulate such an application programmatically in our tests. This is done using the 
running helper. 

We'll create an example in a new file called test/applicative/LoginSpec . scala 
that will contain some tests about login processes. 

The following screenshot shows what it might look like with two sample tests: 



1 package applicative 

2 

3 import org , specs2. mutable ,_ 

A 

5 import pi ay , api . t est ._ 

6 import pi ay . api .test . Helpers ._ 

7 
8 

9 class LoginSpec extends Specification 1 
1G "Login " should 1 

11 "return an OK result" in { 

12 running! FakeApplicationt 1 ) { 

13 // 'getWrappedResult * because it's a Java a_pjs and 

14 // ve 1 re testing via Scala 

val result = cont roll e rs . Application . 1 ogin (). getWrappedResult 

16 

status! result i must equalTo(OK) 

18 } 

19 } 

"have a template vith an HTML form" in { 
21 running! FakeApplicationt ] ) { 

val html - views , html .login! ) 

23 

content Type! html ) must equalTo! "tejd^html " ) 
cont entAsSt ring! ht ml ) must containT^form" ) 

26 } 

27 } 

28 } 

29 } 
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The structure of the test is exactly the same as the atomic one, however we see the 
appearance of a wrapper around our tests called running. 

This method is able to start its first parameter and run the test block that is given as 
the second parameter. 

In this case, the first parameter is a mock-up of our Application; for this parameter, 
a dedicated FakeApplication case class is available in the play . api . test package. 
By running this fake application, we'll have the opportunity to test almost everything 
that defines it, so we can test the rendering of a template or a controller's result. 

The first test we've defined in the previous example is checking that the login action 
in the Application controller will return an ok result, that is, a response with a 200 
HTTP status. 

For that check, we used a matcher that Play! 2 has defined in the pi ay. api. test. 
Helpers object (which, by the way, is the object that defines the running function as 
well). What this status matcher does is retrieve the status of the result (set using the 
ok method in our action) and check it against the 200 constant. 

Something to note before switching to the next test is the usage of 
getWrappedResult on the result of the action. We did this because we're testing a 
Java action using Scala matchers. These matchers are thus expecting Results from 
the Scala world, given that Java Results is just a wrapper around the Scala version. 

The second test is playing a different game. It's checking the validity of a template by 
simply invoking it. This has the advantage of skipping the business logic defined in 
an action to test specific use cases. 

The template we're testing, the login one, expects to return an HTML result content 
that contains a form tag. 

These checks are straightforward; they are performed using the dedicated matchers 
contentType and contentAsString from Play! 2. Where the former is checking the 
encoding header, the latter is reading the body as a string. Also, we can use the 
contain matcher from specs2 to check if a string is part of another. 

So far so good; now we need to run them. For this we keep consistent by running 
test in the console, due to which both the ComparisonTests and LoginSpec tests 
classes will run. 
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Here is the result we would get: 



info] Login should 

] return an OK result 

] RuntimeException: There Is no HTTP Context available from here. (Http. java:117) 

j play .nvc. HttpSContext . current (Http. java : 27) 

] play .mvc. Http$Con text S Implicit. session (Http. java: 117) 

] views. html. main$ . apply ( main .template. scala: 51) 

] views. html .logins* apply (login .template* scalar 34) 

] views. html. loginS* render (login, template .scala: 43) 

] views. html. login. render (login. template. scala) 

] controllers. Application .login (Application. j ava: 53) 

] applicative. LoginSpecS$anonfunSlS$anonfun$applyS3$Sanonfun$apply$4. apply (LoginSpec. scala: 15) 
] applicative. LoginSpecSSanonfunSlSSanonfunSapplyS3$SanonfunSapplyS4.apply(Login5pec. scala: 12) 
] play .api .test .Helpers$. running (Helpers. scala : 33) 

] applicative. LoginSpecSSanonfun$lSSanonfun$apply S3. apply (LoginSpec. scala: 12) 
] applicative. LoginSpecSSanonfun5lSSanonfun$apply S3. apply (LoginSpec. scala : 12) 
] have a template with an HTJ1L form 

] RuntimeException: There is no HTTP Context available from here. (Http. java:117) 

] play .mvc. Http$Con text. cur rent (Http. j ava: 27) 

] play .nvc. Http$ContextSlnplicit. session (Http. java: 117) 

] views. html. main$. apply (main. template. scala: 51) 

] views. html. logins* apply (login. template. scala: 34) 

] applicative. LoginSpecSSanonfun$lSSanonfun$applyS6$SanonfunSapplyS7, apply (LoginSpec. scala: 22) 
] applicative. LoginSpecS$anonfunSlS$anonfun$applyS6$Sanonfun$apply$7. apply ( LoginSpec. bcala: 21) 
] play .api .test .HelpersS- running (Helpers. scala : 33) 

] applicative. LoginSpec$$anonfun$l$$anonfun$apply c;^ apply (LoginSpec. scala: 21) 
] applicative. LoginSpecSSanonfunSlSSanonfun$applyS6. apply (LoginSpec. scala: 21) 

info] 
info] 

info] Total for specification LoginSpec 
info] Finished in 2 seconds, 506 ms 
info] 2 examples, failure, 2 errors 
info] 

info] ComparisonSpec 
info] 

info] Sequence should 

info] + return even integers using 'even' 

info] + contain all squares using ^quaredSeq' 

info] + return even integers using 'even 1 (list independent) 

info] + return something when using ' fetch3' 

info] + return false when using 'biggerThanS 1 1 

info] 



Oh my! Errors again! 

Don't give up; since we saw the application running and have logged in thousands 
of times in the previous chapters, there must have been a mistake somewhere in the 
test or in the architecture. 
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Before debugging, we're going to remove the noise, which produced our first 
successful test, from the ComparisonTests class. To do this, SBT has a special 
command that enables us to target a specific test class to run rather than launching 
all test suites. This command is test -only and we can use it as shown in the 
following screenshot: 

If play- ibook] $ test-only applicative. LoginSpec I 



[info] Compiling 1 Scala source to /home/noootsab/src/book/play- Jbook/target/scala- 2. 9 .1/classes. . . 

[info] LoginSpec 

[info] 

[info] Login should 

[errt ] return an OK result 

[ ] RuntimeException: There is no HTTP Context available from here. (Http . java :117) 

[ ] play .nvc. Http$Context .current(Http. java:27) 

[ ] play. nvc. HttpSContextSImplicit.session(Http.java:117) 

[ ] views. html.mainS.apply(main. template. scala:S7) 

[ ] views. html. login$. applyClogin. template. scala:34) 

[ ] views .html .loginS . render(login. template. scala :43) 

[erro ] views .html .login. render(login . template .scala) 

[error] controllers. Application. login(Application. java:53) 

] applicative. LoginSpecSSanonfunSl$Sanonfun$applyS3SSanonfunSapplyS4. apply (LoginSpec. scala: IS) 

[ ] applicative. LoginSpecSSanonfunSl$Sanonfun$applyS3SSanonfun$applyS4. apply (LoginSpec. scala: 12) 

[ ] play .api. test . HelpersS . running(Helpers .scala:33) 

[ ] applicative. LoginSpecSSanonf unSlSSanonfunSapplyS3. apply (LoginSpec. scala: 12) 

[erro ] applicative. LoginSpecSSanonf unSlSSanonfunSapplyS3. apply (LoginSpec. scala: 12) 

[ern ] have a template with an HTML form 

[ ] RuntimeException: There is no HTTP Context available from here. (Http. java:117) 

[ ] play.mvc.Http$Context.current(Http. java:27) 

] play .mvc. Http$ContextSImplicit .session(Http . java: 117) 

[erro ] views. html. mainS.apply(main. template. scala:57) 

[ ] views. html. logins. apply(login. template. scala:34) 

[ ] applicative. LoginSpecSSanonf unSlSSanonfunSapplyS6SSanonfunSapplyS7. apply (LoginSpec. scala: 22) 

[erro ] applicative. LoginSpecSSanonf unSlSSanonf unSapplyS6SSanonf un$applyS7 . apply (LoginSpec. scala: 21) 

[ ] play .api. test . HelpersS . running(Helpers .scala:33) 

[erro ] applica tive. LoginSpecSSanonf un$l$$anonfun$apply$6. apply (LoginSpec. scala: 21) 

[erro ] applica tive. LoginSpecSSanonf un$l$Sanonfun$applyS6. apply (LoginSpec. scala: 21) 
[info] 
[info] 

[info] Total for specification LoginSpec 
[info] Finished in 2 seconds, 5 
[info] 2 examples, failure, 2 errors 
[info] 

[erro.] Error: Total 2, Failed 9, Errors 2, Passed 0, Skipped 

[ ] Error during tests: 

[ ] applicative. LoginSpec 

[ ] {f ile :/home/noootsab/src/book/play- jbook/}play- jbook/test : : Tests unsuccessful 

[err ] Total time: 8 s, completed Nov 9, 2912 7:29:97 AM 



Since test - only is used when debugging a specific behavior that 
is exposed in a test, this latter test will probably be run many times 
until the fix is found. In such a case, SBT has a special trick called 
continuous command. Simply prefixing a command with a tilde (~) 
will enable this command to run whenever a file has been touched 
(saved) in the sources. In this case, we can use -test-only. 
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We simply called the command by specifying the path to the test class that is to be 
run. In this case, we want a specific class to be run, and SBT (onto which the Play! 
console is built) is aware of the classpath, so you can use tab to auto-complete up to 
the complete qualified name of the test class. 

At least the whole message fits in the console window now and what it says is that 
an HTTP context is required to run the tests. 

Since the Application class we ran is everything but an HTTP stack and since we're 
defining applicative tests, we can't try to run an HTTP server at this stage and so we 
cannot have such HTTP context. 

Furthermore, a login page should have nothing to do with the server; it should only 
show a login form and that's all. We must have done something wrong in our code, 
and where to look is provided by the stacktrace (as usual). 



Looking at the stacktrace, we understand that line 57 of our compiled main template 
expects a session - which is a cookie in Play! and thus it's part of an HTTP context. 

Why is the main template involved here? It's because the login template is using it 
to set the regular layout (the HTML boilerplates such as HTML tags and so on). 

However, to find the problem even more easily than checking the template itself, 
for which we don't have the line number where it has failed, we can go into the 
compiled file itself instead. 

The class file that has been created based on the template is apparently named 
main . template . seal a, so we can simply try to find it by searching the target 
folder, but let me give the path and show its content directly. 

This file is located under the folder /target/scala-2 . 9 . l/src_managed/main/ 
views/html/main . template . scala. 




I took a shortcut here. It is possible to simulate an HTTP context 
as well, and we'll do it next using the router. The fact is that this 
page shouldn't require it. 




If you're using Sublime Text, for instance, just hit 
CTRL + P and type the name of the file to access it. 
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The file looks like the following screenshot: 



25 
26 
27 
2S 
29 
30 
31 
32 
33 
34 
35 
36 
37 
3:3 
39 
40 
41 
42 
43 
44 
45 
46 
4~ 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 




object main extends BaseScal aTempl at e[ play , api .templates , Html , Format [ play , api .templates , Html ] ] 

/**/ 

def a^plW + 1 . 2*/tt itle : St ring) ( content : Ht ml ): play . api . templates . Html = { 
_display_ 1 

Seq[ Any] ( format . raw/»l . 32*/ 1 

-sIDOCTYPE html? 



<html> 

•sheads 

<title=. 



J ,_display_(Seq[Any] ( 1*7. 17* /title) J .format , faw/*7,22*/l </title> 
<link rel = "alternate" type="application/atom+xml " href="http : //localhost : 90QQ/conten" 

<link rel=" stylesheet " media=" screen" href= I , display \ Seq[ Any] /*9, 54*/ routes/*! 

VVVvVVvVVVvVVvVVvVV^vVVvVVv"- VVvVVvVVVvVVvVVvVVvVVVVv 'vWvWyV- WvVVWvWvWyVWWVvV 

<link rel="stylesheet " media="screen" href= I j display Seq[ Any] /*1Q, 54*/routes/*l( 

vw^vWvWvwywwvVvWvyrtArt \^y.y v \i^rv^yv\^yvvv-yvv-y^-y'yv\' -vwwvsv' — — v-y^r^^yv^y-yv^-yvv-yvv^yvv^. 

<link rel = "short cut icon" type="imaqe/pnq" href= , display [Seq Any] /*11.59*/routt 



display_( Seq[ Any] ( /*13. 23*_jfroirtM^*13. 29*/ . Assets . at ( " j avascripts/j 
display_( Seq[ Any] ( /*14, 23* '.' ' ..'4. 29*/ . Assets . at ( " j avascripts/] 
displ ay_( Seq [ Any ] ( /*15 ^T™Z'^£MlZ2J? ■ 29*/ ■ Asset s . at ( " j avasc ript s/cl 
display_( Seq [ Any] ( /»16, 23* - /jjjrtM/^06^ 29*/ . Assets . at ( "j avascnpts/d 
displ ay_( Seq [ Any] i /*17. Zg*jfrwtMj(*17 . 29*/ . Assets . at < "j auascripts/tv 
displ ay_( Seq [Any] ( /*18. 23*/routes/*18. 29*/ . Application , j s) ) , format 



<script S£c 

^script src 

«script src 

^script src 

^script src 

^script S££ 
</head> 
<body> 

^script > 

$C f unctionC ] I . format . rav( { ) . format , rav/*22. 27*/[ 
//dirty example without require, .js 
var tw = new TwitterC $] ; 
console ,dir[tw3 ; 

), format . raw( > 3 , format . rav/*26. 14* /( ) 

</script 5» 

"" ") ,_display_[Seq[ Any] ( /*2B. 10+/0pt ion ( session ( ) . get ( "email "13 / *28. 4G*/ . map/*28. 44+/ 
<hl>Connected as j ,_display_C Seq[ Any] ( /*29.31*/e) ) .format , raW*29.32*/l <£hl 

HOII, format . raw/* 30 . lG+/( 

<div id : 



<span 
<ul > 

</ul> 
</aiv> 

) ,_display_(Seq[ Any] ( /*37. lG*/content ) ) .format . rav/*37.17*/< ' 

</body> 

</ht ml> 



Interesting! A template has been compiled into a Scala ob j ect and what it seems to 
be doing is building a bunch of string values (multiline string values are possible 
in Scala using triple double quotes rather than single ones). 

These string values that are essentially the HTML code from the template are 
interleaved with Scala calls to a _display_ function, which takes the Scala code 
to be executed and dumps its result in the output. 

The line that was erroneous in our tests was the 57th one, and what we can see in this 
line is a call to Option (session ( ) . get ( "email" ) ) . 
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That's true! We're in the main template, which is the base of all high-level templates 
and that uses an active session. This doesn't make much sense, because if we 
consider the login page, this one mustn't rely on the existence of a session since it's 
the entry point that could create it. 

So, we know our architectural mistake and we also understand why it never 
failed —because we ran it in a real server that can create an HTTP cookie! 

Although we know what our error is, we still have to find it in our original main . 
scala . html file, which can become a painful task when huge templates are involved. 
However, Play! Framework 2 has foreseen this problem and tells us which is the line 
number in the template file as well. Indeed, back to our main . template . scala file at 
line 57, right before the call to Opt ion, we see the / *28.io* / comment. This comment 
refers to the line in the template that has generated the following Scala code. 

Now we go to our main . scala . html file at line 28 and character 10. 



5 <html> 

<head> 

<t itl e»gt it 1 e </t itle> 

<link rel="alt ernat e " t ype=" application/at om+xml " href =" htt p : //local host : 9QOQ/cont ent /at om/me@@home 
<link rel="stylesheet " media="screen" href="@routes , Assets , at T'st^les^h^ts^iiain , ess" ) "> 

10 <link rel="stylesheet " media="screen" href="@routes , Asset s , at r'^xt^sKe^s^hDO^ .ess" )" 

11 <link rel="shortcut icon" type="image/png" href="@rout es , Asset sTatT^I|^e5^favicon .ojnc- ") "> 

12 

-■script src="(arout es , Asset s . at ( "^jaj/a^cjryitjs^jqjj^rj -1 , 7, 1 , min , js" ) " t ype="t^xt^fl^sc B rij^t "><fscript> 
^script src="@rout es , Asset 5 . at 1 v ^ w ^ w ^ w ^ w ,.,.^.^X:li ■ ^ orm, Jv?') " type="t:^ w ^ wwwwiv script* 
^script src="@rout es . Asset s . at ( "^.^ vw ^ w ^ vw ,, .^^££5) 'il" > type="t^ v ^ wwAwA 
<script src="@rout es . Asset s . at ( M ^avascri^^2BilHsiix^ ■ 11 ' " ' ■ 
~: . = VVWA . W 

•• ' : .*: : src= ' @rout es . Application .j^s ' t - ^^^^^.^^^i^t ' •<^script > 
</head ■ 
<body> 

21 *:script> 

22 $> function!) { 

23 //dirty example without require. jj; 
var tw = new Twitteri $) ; 

console .dirt tw) : 

26 >| 

27 </script> 

@Option! session! ) . get ( "email " ) ) . map {e=> 
<hl>Connected as •!<■• hi 

30 } 

<div id="twitter-pane" style=" display : none; position : absolute; top:0pxj left : Qpxj background-color : I 
--span style= "font -weight : bolde r; fl oat : right j margin : 2px; width : lem ; t ext - align : cent e r" >x<. span 
33 <ul> 

34 

35 </ul> 
</div> 
^content 
</body> 

39 <■ html 



Oh yes, the check on the connected user is already done here; this means that every 
page that will rely on this template to set its HTML boilerplate will involve a check 
in the cookie, irrespective of whether it makes sense or not. 

Moreover, if we take a deeper look at this template, it includes way too much 
information, such as the scripts declaration, the initial creation of the Twitter 
JavaScript tool, and even the tweets panel that is declared there. 
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Since it's a common mistake, there is a common solution! The solution is to create 
two levels of main templates, one for the HTML boilerplate (such as the DOCTYPE 
declaration and common scripts) and another that includes everything needed for 
the application to run — the second will rely on the first one. 

Having created them (refer to the following list), we will have to go through each 
dependent template and decide whether it is part of the application business 
(which requires a logged-in user) or not. 

To do so, what has to be done is to create another template that we'll name 
mainExtended. This new template will hold the following: 

• A call to the main template (which we might rename to something like 
"bootstrap", for instance) 

• The check in the cookie for a logged-in user 

• The scripts that are only relevant while the application business is involved 
(the chatrum itself) 

Finally, the Twitter part will be moved to the dashboard/index . scala . html 
template, which is the only place where it'll be used. 

This means that the main . scala . html file should be quite empty now, as shown in 
the following screenshot: 



1 g( title: St ring) ( content : Html) 

2 

3 < l DOCTYPE lt»l> 
4 

5 Irtml 

6 <head> 

=title:>@t itl e<, title:. 

<link rel= " alt ernat e " t ype=" application/at om+xml " h ref= " http : //local host : 9000/cont ent /at om/me@@home 

9 

10 <link rel="shortcut icon" type="image/png" href="@rout es . Asset s . at (" images/f avicon . png" )" > 

11 

<link re 1= " st ylesheet " media=" screen " hi ref="@rout es . Asset s . at [ "st yl esheet s/main . ess " ) " > 

13 <link re 1= " st ylesheet " media=" screen " n ref="@routes . Asset s . at L "st yl esheet s/book . ess " " > 

14 

15 <.'-- jQuery 

16 <script s rc=" Sroutes . Asset s . at ( "i a vase ript s/i query -1 . 7. 1 . min . i s" ) " t ype="t ext/i avasc ript " ></script> 

17 <.'-- import js reverse routing --> 

18 <script src='@routes.Application.is' t ype= ' t ext /i avasc ript ' script > 

19 </head> 

20 <body> 

^content 

22 </body> 

23 e/hrtml = 



The main template now contains only the common resources that are needed across 
all other templates, which are the jQuery library, the JavaScript reverse routers, and 
the stylesheets. 
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The mainExtended template is almost similar to what we cut from the main template. 
Take a look at the following screenshot: 

pllitic: String) (content : Html) 

2 

@main(title) { 

@Option( session! ) . get ( "email " ) ) . map {e=> 
<hl:--Connected as ge</hX> 

6 } 

^content 

9 

1Q <!-- JavaScripts --> 

^script src= "@rout es . Asset s . at ( " j^S^J^ES^XiSH^^ ■ ^ orm ■ 1^ " ) " type- " J^X^j^^^Xij^ " >< /*tript> 

12 

13 <script src= "@rout es . Asset s . at ( " i avascript s /chat room. is") " type="text/iavascript" ></.script:> 
-script src= "@rout es . Asset s . at "ia vase riots/dashboard .is" " t ype= "t est /] avascript " ></ script* 

15 } 



It simply calls the main template by giving its own title, and the second parameter 
is only another wrapper over its own content variable. The wrapped code involves 
the user login information in the session and will insert the JavaScript at the end of 
the body (a common technique to accelerate the loading time of a web interface). 

Up to now, the Twitter integration hasn't been restored. Actually, since we're pretty 
sure that this tool will only be used in the dashboard, we can delegate its loading to 
the dashboard/ index, scala .html template as follows: 



15 


@mainExt ended! "WeLcome on PLay! 2 - ChatRum") t 




16 


-=:div id="tvitter-pane" style=" display : none; position : absolute; 


top : Qpx j left :Qpxjbackgrour 


17 


- span cl a s s= " cl o s e " >x -=:./ span 




IS 


■=:ul> 




19 






20 






21 


</div> 




22 






23 


^script s rc= "flroutes . Asset s . at ( "javascripts /twitter .is")" t ype= 


"text /i avascript '></scrjjjt> 


24 


<scnpt> 


25 


$ function 1 ) { 




26 


window , chat rum = O 




27 






28 


window, chat rum , dashboard = new Dashboards { 




29 


el : $■ "-^dashboard" .1 , 




30 


closed :@dashboard Form, value. isDe fined 




31 


>|j 




32 








var tw = new Twitter $ ; 




34 


}' J 






</script> 





We will add the tweets container, the script loading instruction, and finally the 
JavaScript instance of the Twitter tool when the whole document is ready. 



You might be wondering why we left all the JS libraries in 
mainExtended, and you would be right because we should 
have dispatched these libraries as well. We left them there for 
illustration purposes. 
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In this template, we can also notice that we changed the call from main to 
mainExtended. Indeed, it's our last step. Review all the templates that are using the 
main template and check whether they should or should not use the extended one. 
Of course, login . scala . html should remain unchanged. 

Having done that, we've cleaned our application up a bit and we're now ready for a 
second check on the applicative side by running the test -only command again. 



[play-jbook] $ test-only applicative, LoglnSpec 

[Info] Compiling 2 Scala sources to /home/noootsab/src/book/play- jbookj 

[Info] LoglnSpec 

[Info] 

[Info] Login should 

[Info] return an OK result 

[Info] have a template with an HTML form 

[Info] 

[Info] 

[Info] Total for specification LoglnSpec 

[Info] Finished In 2 seconds, 990 ms 

[Info] 2 examples, failure, 9 error 
[Info] 

[Info] Passed: : Total 2, Failed 9, Errors Q, Passed 2, Skipped 9 
[success] Total time: 12 s, completed Nov 9, 2012 3:18:42 PM 



Here we are! Now our login page is quite done, but what about the login validation 
in the database and so on? Right! 

It'd be worth it now to spend some time on this as well, checking, for instance, 
whether an unknown user has been redirected to the login page again or not. For this 
there is the enter action in Application that we've to test; the problem with this 
action is that it requires some data in its body. So, it's not like login that we were 
able to call directly. 

In this case, we really need a request, at least a mock-up, that is a FakeRequest 
instance. This mock-up can mimic everything a real request can do, so it'll enable 
us to put some data in its body (if it's a POST or PUT request). Then we'll have two 
ways to use it: 

• By calling the action (enter) with it 

• By using the router to send it to the target URL (/enter) 
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Okay, we should create such a FakeRequest matching the requirements of the enter 
action, which is the only URL-encoded email parameter in the body. Using this 
information, the action will check in the database if a User exists with this e-mail. 

The following screenshot shows two examples, one for each option: 



"that fails will redirect to the login page again" in i 
running(FakeApplicationU) { 

val fakeRequest = new play .test . FakeRequest ( POST, "/enter") //use the Java Test API!! 
val withEmail = fakeRequest .wit hFormUrl EncodedBody( Map( " email " -> "unknn^^ 

36 

val result = play . test . Helpers .call Action (cent rollers. routes.ref.Applicat ion. enterl 1 , withEmail ) 

38 

redirect Locationf result. get WrappedResult) must beSome.which(_ == "/login") 

40 > 

41 } 

"(using the router) that fails will redirect to the login page again" in { 
running(FakeApplication( ) ) { 

val fakeRequest = new play .test . FakeRequest ( POST, "/enter") 

val withEmail = fakeRequest . wit hFormUrl EncodedBody ( Map ( " email " -> "unknowniSex ample . com" ) ) 

46 

val result = play . test . Helpers . rout eAndCall (wit hEmail ) 

48 

redirectl_ocation( result . getWrappedResult j must beSome . which(_ == "/login") 

50 } 

51 } 



Indeed, they are both identical; only the way to call the action is different, but they 
are equal. Before tackling these lines, we'll review what has been done. 

First, we created a FakeRequest (from the Java test API) and updated its body 
with what the enter action expected, that is, the email parameter. This email was 
then encoded as a form URL, since the enter action is dealing with such content 
only. Then, this request was served using the callAction Java test helper. This 
helper requires an action to be called with a request. Exactly what we want to do! 
So, we used it by giving it the enter action reference available under the package 
controllers . routes . ref that gives access to the action instance that Play! 2 will 
generate based on the static method defined in the Application controller. The 
second parameter is simply our request. 

Using callAction is the key point here, since it'll simulate the action on the request. 
However, note that we're still using the Java version of the test helpers to access the 
action instance and call it. Thus, the action will have access to the request's body to 
fetch parameters and so on. 

In this case, we're trying to enter the application using a given e-mail that doesn't 
exist in the database, so the enter action should redirect to the login page. 
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This redirect information can be retrieved using the redirectLocation helper by 
doing two things at once, namely checking if the status is one of the semantically 
equivalent ones (such as moved permanently or temporary redirect) and then 
checking if it returns the Location header. 

Since either the status can be wrong or the header can be absent, the return type is 
Option. Given that we expect it to exist, we can simply check that header to be an 
instance of Some which wraps the "/login" string. 

In this test, we didn't use any HTTP stack (not even a fake one). For such use cases we 
can use another helper to call the action, that is, the routeAndCall one. Its usage can 
be seen in the second example shown in the previous screenshot. The preparation and 
checks are exactly the same but the call itself is different. However, you'll probably 
only use the second version that is less verbose, but it's important to know that no 
magic is involved. That's what the first version is showing. All actions are compiled 
into dedicated objects that will be available for testing purposes (in this case). 

The really interesting thing to note so far is that we used the database to check the 
user's existence without (re) configuring or even mentioning it. It worked because 
we ran a fake version of our application, and also because our application is using 
a database. 

On the other hand, we're in the easiest situation, where the development database is 
the same as the tests one. In this case, it's an in-memory database that is started with 
the application. Most of the time, we have a dedicated test database for efficiency or to 
reduce resource consumption while testing or, especially, to target different vendors 
(MySQL, SQLite, Oracle, PostgreSQL, and so on). This can be achieved by giving an 
extra parameter to our FakeApplication, as shown in the following screenshot: 

vaL otherDatabase = Map( 

( "db. another. driver") -> OTHER_DB_DRIVER_CLASS_NAME J 
( "db. another, url") -> OTHER DB URL CONNECTION 



"Test using another database " should { 

"do stuffs correctly" in { 

running! Fa keApplicationffakeApplic at ion(ot he rDat abase ) ) { 
//da some checks using the 'another' database parameters 

> 

} 
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But wait; if it simulates an HTTP stack, we could check for a valid user to connect 
and that his/her e-mail will be stored in the session! How about the test shown in the 
following screenshot: 



"succeed and redirect to the dashboard page" in { 




running( FakeApplicationC ) ) { 




val address = new models . Addressf ) 




address . fullSt reet = "Smurf, 1" 




add ress . count y = "Smurf^^ViTTage" 




address . count ry = "SL" 




address . save 




wal user = new models . User( ) 




user. name = "Grandpa" 




user. email = "grandpai3smurf.com" 




user. age = 109 




user. gender = false 




user. address - address 




user . save 




val fakeRequest = new play.test.FakeRequest( POST., "/enter" ) 




val wit h Email = fakeRequest. wit hFo rmUrl En coded Body ( Map ( " email " - 


> "grandpaipsmurf .com") ) 

Vv VWVv W vVv'v Vv VWVv W- 


val result = play .test , Helpers , routeAndCall (withEmail ) 




sessionC result . getWrappedResult ) must not beNullj 




session [ result . getWrappedResult ) , get ( "email " ) must b e So me .which ( 


== "grandpaftsmurf , com" j 


redirect Location( result .getWrappedResult) must beSome .whichC 

> 

} 


"/dashboard" ) 



What's being done here? We begin by creating an instance of a User with its 
mandatory Address reference, then they are both made persistent using save, and 
finally we create a fake request targeting the enter action. Note that we update the 
request with the new user's e-mail. 

After having asked it to be routed and called, we must check what the result of this 
action should be. The enter action will check that the e-mail corresponds to an 
existing User. If so, it'll store the e-mail in the session and redirect the page to the 
dashboard index page. The last three lines of the test check these things by doing 
the following: 

1. Checking that the session is not null using the helper session that extracts 
the session object from the cookie. 

2. Checking that the session has an entry named email. When retrieving its 
value (instance of Option type) from the session, we check that it should be 
an instance of the Some type. Where such instance extends the Option type 
by providing a content (the e-mail in this case). 

3. Checking that the header Location and the status define a redirection to the 
index page of the dashboard. 
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That's it; we're now able to test anything in our application, right from the top layers to 
the bottom ones. Plenty of other test helpers are also provided by the framework, but 
it'd be overkill to present them all here. The best would be to check Scala/ Javadoc of 
the Helpers classes when needed. 

We've just said that the top layers are testable; it's definitively true for the server 
side but not for its exported features that compose of the workflows enabled 
by a web application, such as the operations that a service is exposing or the 
UI that it is presenting. 

For this, we'll have to write different kinds of tests that have yet another more 
complicated and more complete set of needs. This is the topic of the next section. 

Testing workflows 

In this last section, we'll cover another level of tests that is able to test exposed 
features involving workflows crossing the atomic services provided by an 
application. This level of testing is also able to test interfaces opened to the wild, such 
as HTTP REST interfaces. These tests are probably the most important ones because 
they're asserting that our application is presenting features to the end user and these 
features are working well. That is, they are asserting that we've created added value 
to our application for the end user. 

These kinds of tests are also the most difficult ones because they include third-party 
products or infrastructure components such as a browser and an HTTP server. 
However, we'll see that Play! Framework 2 is aware of these requirements, and it 
prepares everything for us in order to let us focus on the test logic only. 

As in the preceding sections, several dedicated helpers are available for our tests. The 
first one is an overloaded version of the running helper. This version has an extra 
parameter, a server. Since it can be quite cumbersome to create or integrate a server 
in our test environment, Play! Framework 2 has defined a wrapper around a Netty 
server that is accessible through the TestServer class. 

A TestServer instance is created using three parameters: 

• The port where the server must listen 

• An Application to be run within the server 

• An optional SSL port 
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By having such a server running, it'll be possible to test the features, such as 
the Twitter proxy in our application, that we're exposing to the outside world. 
Let's see an example: 



CornparisonTests. scala x 



TwitterSpec.scala 



i 

2 
3 
4 
5 
6 
7 

s 

9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 



package workflow 

import org , specs2, mutable ,_ 

import play . api .test ._ 

import play . api .test . Helpers ._ 

import play . api .libs . j son , JsSt ring 
import play . api .libs .ws ,WS 

class TwitterSpec extends Specification { 
"Twitter search service " should { 

"return tweets with the user name when searching for mentions" in { 
// NOW we're running a server! 
runninglTestServerl 3333, FakeApplicationl ) ) ) { 

//we use our application through a real HTTP request. 

val response = await 1 WS , u rl 1 " htt p J_//1 ocal hnst j_3333J^/tw/ien1 ians /nooot sab ° ) . get 1 
// we assert that the responsernustpegk^ 
response . st at us must equalTo(OK) 

// we parse the response into as js_on 

// then we retrieve all "tweet" properties in this converted response 
// which tweet texts (an array) must all respect a certain pattern 
( response , j son \\ "tweet") must haveAllElementsLike { 

// the pattern is checking the String type 

// this string must itself matching a regex 

case s:JsString => s.toString must beMatcningl " , Jno^ootsab , *" ) 

// if not a String =» the test must fail 

case x => kot" 'tweet' must be a String : " + x) 



} 



What has been done here is that after the classical test structure, we used the 
running helper with a TestServer that must listen for HTTP requests on port 3333 
and that starts a simple FakeApplication like before. 

Then we directly took the opportunity to use this server by defining a call to our own 
application, targeting the Twitter controller, especially the mentioning action. 

Such a call is exactly the same as it would be for any other web service, as in this 
case, our application is also a web service. So, we're using the WS API that will hit 
the test server on port 3333 by using the routed path for this action. 

Recall that this ws#url method will return a promise of a result, that is to say that the 
result won't be available until we explicitly wait for it. Waiting for Promise to return 
can be done using another helper called await. 
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This await helper takes a Promise instance and blocks the current thread until the 
underlying promised result has arrived; then it returns this result back. That's why the 
value of the variable response is already the complete response of the web service. 

After doing a sanity check on the response status and confirming that it is OK, we 
directly moved to a more specific one by asserting that all tweets must contain the 
expected username. 

Since the mentioning action is returning a result with a JSON-encoded body, 
we can use the double backslashes (\\) operator on it to retrieve all tweet messages. 
This will return a sequence of the value of all the properties named "tweet" in the 
JSON tree. 

For this, we have to first parse the body of the response as JSON using the j son 
method, after which we will be able to extract all the tweets out of it. The rest of 
the test is a specs2-specific check for sequenced content. 

All we said is that the text of all the tweets in the sequence must have a type 
string (otherwise the test fails), and each of them must also contain the 
searched username (noootsab). 

Launching the test in the console will give the report shown in the following 
screenshot: 



play-jbook] $ test-only workflow. TwitterSpec 

info] Compiling 1 Scala source to /home/noootsab/src/book/play- jbook/target / 

info] TwitterSpec 

info] 

info] Twitter search service should 

info] for mentions returns tweets with the user name 

info] 

info] 

info] Total for specification TwitterSpec 

info] Finished in 3 seconds, 558 ms 

info] 1 example, failure, 9 error 
info] 

info] Passed: : Total 1, Failed 0, Errors 9, Passed 1, Skipped 
] Total tine: 7 s, completed Nov 22, 2012 7:Q3:26 AM 



Success! 

This example is representative enough of what can be a service's feature test; 
however, an application is not only composed of services to be used by other 
programs. A web application targets real users most of the time, who are using 
browsers and clicking and entering text and so on using a keyboard or mouse. 
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We won't talk about mobile-native clients in this book, but since Play! 
Framework 2 is not embedding anything to build such applications, 
it's acceptable. However, these native applications are to be tested 
alone, in which the used services are assumed to be correct. I 

For such high-level tests, Play! 2 uses Selenium. Even if we can use the classical 
version of the Selenium API to test our stuff, Play! 2 will integrate a rather better 
API on top of it called FluentLenium. 

Selenium (and its wrapper) is able to either emulate a browser in-memory or use 
specific drivers to launch tests. To use these drivers, we have to first set up our 
machine with the targeted browsers (Safari, Firefox, Chrome, and others) and install 
the associated Selenium web drivers. 




• Since it's not the purpose of this book to provide in-depth details 

% \ on how to efficiently use Selenium, we'll use the in-memory 
r^"^ version of the browser that doesn't require any other setup. J 

What we're going to do now is to see how easy it is to test a web application end to 
end involving as many layers as the application is using. 

To illustrate this, we'll test an unregistered user logging in to our wonderful web 
application chatrum. Since he/ she really wants to use it, he/ she will have to go on 
the register page wherein he/ she will have to enter all the information required by 
the HTML form (and the related action on the server side). 

Having submitted the registration form, he/ she will be able to connect to the 
application using e-mail and then use the dashboard. 

This workflow will require the test to simulate a lot of things on the client side, click 
on buttons, type text in some input fields, select a box or drop-down lists, and so on. 

Under the sea, we'll need the full server to check the validity of the inputs, the 
existence of the user, and to store information in the session. 
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This kind of setup can become a nightmare really quickly, but not with Play! 
Framework 2. Here is how we're supposed to do what is presented in the 
following screenshot: 



class RegisterSpec extends Specification { 
"Unknown user " should { 

"be able to register and then login" in { 

running(TestServer( 3333. FakeAppl icat ion ( ) ) , HTHLUNIT) { browser => 

/* 

DO SOMETHING WITH THE BROWSER: 
click, select, navigate, ... 

»/ 
/♦ 

REGULARLY CHECKING THE CONTENT 



So easy! There are only two things we have to do compared to the previous test, 
as follows: 

• Pass a second argument to the running helper, which is the web driver we 
want Selenium to use — constants such as HTMLUNIT and FIREFOX are 
available in the helper class (Helpers . scala) and they define the web driver 
to be used for related browsers. 

• The content of the running helper, rather than being a simple block, is now 
a function taking one argument called browser, which is an instance of the 
web driver. Note that the creation of this instance is out of our hands because 
it will be handled by the framework. 
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Another point is to use this driver to simulate a user navigating the application, 
generating data and requests. We can do this using FluentLenium, as follows: 



package workflow 



import org , specs2. mutable ,_ 

import play . api .test ._ 

import play . api .test . Helpers ,_ 

import seal a. collect ion. JavaCo inversions. _ 

import seal a. collect ion. JavaConverters._ 

import play.api.libs.json.JsString 

import play . api .libs .ws .WS 

import org, fluentlenium. core, filter. FilterConst ructor ._ 

class RegisterSpec extends Specification { 
"Unknown user " should f_ 

"be able to register and then login" in { 

running(TestServer( 3333, FakeApplication( ) ) , HTMLUNIT) I browser => 
val baseURL = "http : //local host : 3333" 

browser . goTo( baseURL+" /login" ) 



browser . $( "a" ) , click ( ) 

browse r.url must be_==( baseUF^+" ; /foj^rn^u^er" ) 

browser .$( "#gender_radio label "), get Texts , get ( 0) must be_==( "Female" ) 
val sauronEmail - "sauronSpuppet .land" 

browser . fill [ "input " , with ( "type" ). not Contains! " radio" J J . with I 

sauronEmail , 
ISO.toSt ring, 
"Mordor, 0" , 
"Middle -Earth" 

]_ 

browser . $[ "#gender_radio_f alse" ) , click ( ) 
browser . click ( "option" . withText ( " Arda" ) ) ; 
browser .submit ( browser . $( "f orm" ) J 

import ] ava , util . concurrent .TimeUnit . SECONDS 

browser . await ( j . at Most ( 1, SECONDS) . until ( "input " ) ,withName( "email " ) . isPresent ; 

browser . f ill ( browser , find ( "input ")) , 'wit h * (sauronEmail) 
browser .submit ( browser . $( "f orm" ) ) 

browser . await ( ) . at Most |1, SECONDS) . until ( "#dashboard" ) . isPresent ; 
browser, url must be_==( baseURL+'Vdashboard" ) 

browser .$( "hi" ). get Texts . get ( 0) must be_==[ "Connected as " + sauronEmail) 

} 

} 

} 

} 
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Wow... we've done a lot. It'd be worth reviewing it a bit, so let's do it step by step. 

Firstly, we'll store the base URL of our application and then we ask the browser to 
navigate to the login page. 

val baseURL = "httjp : //local host : 3333" 

. ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . . ■ . ■. . 

browser , goTo[ baseURL+ " /"Login" ) 

Since we're running a server on port 3333 (using the TestServer class), our web 
application's base URL is obviously the value of baseUrl. 

Then we ask the browser to navigate to the login page by using its endpoint (/login) 
as configured in the route file. Since the user has not been registered yet, he/ she has 
to click on the link to be redirected to the register page. 



browser . $( "a" ] , click ( ) 

browser, url must be_==( baseUI^+ "^^orji^jsej " ] 

browser .$( "#gender_radic 1 abel "). get Text s . get ( Q) must be_==( "Female" ) 



Some interesting things here. First, the browser object has a method $, like jQuery, 
that enables us to search the DOM for elements. This find method (its other name) 
takes a CSS selector and supports most CSS3 features (pseudo classes, attributes, and 
so on). In our case, we locate the link (<a> tag) and ask Selenium to simulate a click 
on it by simply calling the click method on the element. 

Given that this link redirects to the register page, we can check right after that the 
new browser's URL is now pointing to the route of the register action. But also, we 
can check that artifacts are present on the page, like the example shown previously 
that checks that the first label HTML element under the gender radio input 
HTML element contains the Female string. The register user page shows a form 
containing a lot of information, such as the username and e-mail address. What we 
must do now is fill them all. For this, we'll start by filling the textual inputs, then 
we'll deal with the radio buttons and select boxes. 



val sauronEmail = "sauronflpuppet .land" 

browser . fill ( "input " , with ( "type" J . notContainsl " radio" J ) . with 

sauronEmail , 
15Q.toSt ring, 
"Mordor, □" , 
"fOdle- Earth" 

I 

browser . $( "#g.ender_radio_f alse" ) , click ( ) 
browser . click ( "option" , withText ( " Arda" ) ) ; 
browser . submit ( browser . $( "fan"] J 
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Filling an HTML form can be done using the browser's fill method that takes 
two parameters to retrieve all the form elements that are to be filled in. The first 
parameter is the CSS selector; the second can be used to add constraints on the found 
elements. In this example, we fetched all the input elements and then removed the 
radio ones (using the type attribute). 

You may have noticed the backticks around the with method. 
This is because with is a reserved keyword in Scala, and Scala 
enables us to use tricky names or reserved words if they are 
surrounded by backticks. 

Having collected all the needed elements in the form, we can now ask them to 
receive values. This can be achieved using another with method, by passing it the 
values in the same order as the order of the elements in the form. 

That was easy for the text-based input fields, but our form has two other fields, 
namely a radio button (gender) and a select one (country). Both of them don't take 
string as a value but react to clicks, so we asked the browser to search for them and 
click on the relevant parts. 

Now that the form has been filled completely, it's time to submit it. This will be done 
with the submit method on the browser using the form element to be submitted. 
Submitting a form requires a server-side action that might take some time to return. 
This is why we can ask Selenium to wait a certain amount of time until the server 
replies. In our case, we asked the test to wait until an input element with a named 
email appears in the DOM (Document Object Model) simply because the login page 
has it, and register should redirect to the login page. 



import j ava , util . concurrent .TimeUnit . SECONDS 

browser . await ( ) . at Host |1, SECONDS) . until ( "input " ) .withName( "email. " ) . isPresent ; 

browser . f ill ( browser , find ( "input ")) , "with" (sauronEmail) 
browser .submit ( browser . $( "form" ) ] 



We were asked to wait for a second until the input named email was present. When 
this field was present, we did the same thing again with the login form; we set the 
e-mail value and then submitted it. So now we're logging the user in. 

To end the test, we should now check that the result of the login action is the 
dashboard page itself. 



browser . await ( ) . at Most |1, SECONDS) . until ( "#dashboard" ) . isPresent ; 
browser, url must be_==( baseURL+"/dashboard" ) 

browser .$( "hi" ). get Texts . get ( 0) must be_==( "Connected as " + sauronEmail) 
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Before any checks, we asked the browser to wait for an element with an ID that is 
equal to dashboard to be present. Then we checked that the URL is the expected one 
(the route of the Dashboard#index action). Finally, we verified that the hi tag has a 
text containing the e-mail used to register the user and log him/her in. 

Starting from here, we can now envision all the tests we could perform for for 
workflows that involve a chat, the creation of topics, and so on. 

At this stage, we've reached the higher level of functional testing without having to 
set up anything more than what was set up for the application itself. 

Summary 

In this chapter, we had an overview of all the testing phases using the bottom-up 
approach for various kinds and amounts of tested features. We also took the 
opportunity to review the helpers provided by Play! Framework 2 that enable 
us to focus on the tests themselves rather than the set up of the application 
components or tiers. 

Since tests are a good starting point to learn Scala and to slightly introduce this 
language into an existing application, we preferred this language over Java to write 
our tests. But for those still preferring to stay in the pure Java world, you had enough 
information about the helpers provided by Play! 2. Furthermore, those helpers and 
mock-ups can be used along with any other Java testing framework you like. 

There are plenty of amazing testing frameworks in Scala, however Play! 2 is 
particularly well integrated with specs2, so we followed this track too. 

Based on this, we separated the tests into three main logical sets, namely atomic, 
applicative, and workflow. Although each of them have their use cases and their 
needs in terms of infrastructure or third parties, the helpers of Play! 2 were there to 
avoid us bothering with such integration. 

At the end of this chapter, we're able to test every single part of our application 
by creating as many specifications our application needs to respect (where a 
specification explains a certain amount of features). 

So it's now time to deploy our application using a continuous integration tool after 
having asserted that the tests are not dependent on our machine. This is exactly the 
purpose of the next chapter. 




Code Once, 
Deploy Everywhere 

In this book, we saw how the Play! Framework 2 can be used to create great web 
applications. However, we only saw them running on our machine, which is a dev 
machine. So far, so good, but a web application is not meant to be used this way; it 
has to be productionized, which requires it to be deployed on a so-called Prod server. 
A Play! Framework 2 application can be deployed in several ways, for example, in 
a servlet container, such as Tomcat. However, in this chapter we'll concentrate on a 
particular use case; cloud deployment on a Platform as a Service (PaaS). 

But, wait! There is something that a web application needs before before it can be 
released to the end user. It needs a neutral environment, which asserts that the 
application is delivering its features correctly. Nowadays we like the Release Early, 
Release Often vision, but for that to happen we need to have an automated and 
continuous eye on its quality. 

That's why we end up in a more general process called Continuous Delivery. 
Continuous delivery means that the work done by a developer has to be checked 
into a decentralized repository. This repository will be used by a tool, a Continuous 
Integration (CI) server, to check that the modifications aren't leaving the application 
in a stale state. 

At this stage, we're not yet done because the final user cannot use the newly added 
functionality (or bug fixes). For that, we need the CI to automatically deliver the 
status to a deployer (it could be the CI itself or a plugin), which will be able to 
redeploy the application when the status is okay. On the other hand, if the code base 
is failing the CI, we need it to send events to the dev team, which should pause its 
current tasks and work on the problem until the application is stable again. 



Code Once, Deploy Everywhere 



So far, so good, our application will be continuously managed from the dev to the 
user. But is it running fine in any case? How do we ensure that? Don't we need 
another handy tool out there, such as an admin interface, which will act as an 
applications' doctor? 

In one word, a monitor that will enable us to react to strange runtime behaviors, 
utilization peaks, and so on. Fortunately, this tool is already part of the Typesafe 
stack (remember that Play! 2 is the web layer of this stack) and it is named 
Typesafe Console. 

In this chapter, we'll cover these three pillars of web application management, 
essentially using a dedicated service on the cloud for each of them: 

• Continuous Integration server using CloudBees DEV@cloud services (SaaS) 

• Deployment on Heroku (PaaS) 

• Monitoring using the Typesafe Console 

Continuous Integration (CloudBees) 

In this section, we'll talk about CloudBees, which is the provider of a blazing service 
for Jenkins, the famous open source Continuous Integration server. 

This is not the only great service this company is offering of course. Its portfolio 
spans every single step of a Continuous Delivery process. And they do it very well 
from the code repository to the runtime and even some monitoring through add-ons. 

However, we'll specially focus on their DEV@cloud product, which is the CI service. 

So, CloudBees is a Java Platform as a Service that aims to completely abstract the 
Infrastructure as a Service (IaaS), which CloudBees uses on its side to provide a clean 
and easy way to manage an environment that builds, tests, and runs a web application. 
As a fully dedicated Java platform, it is particularly well integrated with the ecosystem 
tools and framework built on top of this language and the related languages, such as 
Scala, Clojure, JRuby, and so on. CloudBees is special in several aspects, the first is 
that it's a freely-accessible panel of services, at least until the thresholds are reached. 
Nevertheless, these thresholds are sufficiently high enough to enable up to three 
regular developers to run their tests. On the other hand, the runtime needs are not 
dependent on the number of coders, but are dependent on its quality and popularity. 
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Alright! Before starting with it, let me first introduce CloudBees' two major products: 

• DEV@cloud: This service provides a perfect environment in which to test a 
web application. It's completely integrated with a provided code repository 
or with any code repository we own and is publicly accessible. It can also be 
fully automated using hooks around the code repository that it's using for 
running the tests. 

• RUN ©cloud: This service is the runtime environment that is available in two 
flavors depending on your needs. There is the multi-tenant and the dedicated 
one. Since they're abstracting the underlying infrastructure, we could own 
fully dedicated machines (virtualized) or parts of machines (shared with 
other applications) without any extra configuration. 

After this short introduction to the CloudBees services, it's now time to get back to our 
initial concern, that is, how to use CloudBees to continuously check that our Play! 2 
application remains stable with each modification saved in the code repository. 

First of all, we have to go to their website at http : //www . cloudbees . com and create 
an account. Having done that, we can now log in to their website and access our 
administration console: 




The preceding screenshot shows a brand-new account without any application, 
so it's time to create our chatrum application. Here's where the magic starts! 

Indeed, since CloudBees is a Java PaaS, and it's clever, it has eased the work for 
developers wanting to bootstrap a new application on their framework of choice 
using what are called ClickStarts. 
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A CloudBees' ClickStart is in fact a wizard to create an application using several tools 
commonly used together. Thus, the created application will include configuration 
files for them, or even the glue between them. That's not all, the extra tools will be 
preconfigured as well, such as the Continuous Integration server or the deployer. In 
our case, we'll find it very handy that we can create a Play! Framework 2 application. 
CloudBees recognized very early that Play! 2 will play a major role in the web world 
in the coming years. Therefore, they created an end-to-end wizard, which can grasp 
our application's code, preconfigure a Jenkins server for it, and also help the Jenkins 
server to be able to deploy it. Moreover, it is done in just a few clicks. Let's see it in 
action; click on the upper-left icon in the navigation bar of our admin interface (with 
the label ClickStart). We should get something similar to the following screenshot: 




Look at the previous screenshot. It's right in the center of the page, surrounded 
by giants such as J2EE 6, Node.js, Hibernate and Tomcat, and a Facebook 
application environment. 
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It's time to go ahead and click on the Play! 2 icon! This click will ask CloudBees to 
prepare a Play! Framework 2 environment, which we'll need to test our application 
(or run it). Before that, it will ask us for a name for our application: 




The input field right below recaps what will be created for our application, in 
terms of services and so on. We'll name our application chatrum and click on 
Create App >. 
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Plenty of infrastructure tasks were realized after just a few seconds of preparation, 
which would have taken a full week of work without CloudBees. In the following 
screenshot, we see that our server is ready with some available tools: 



CliekStart 



Play! Framework 2 



Application Components 
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Management URL 
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9p 



sshi.OghQgrt.clc^bee^.cor^'anrJy-petreJlactorLini.gh 



Web Application chat rum 



Jenkins build 

Management URL 
rTtt|rc://anQy-pErtTeta.c i.ck^b^ 



Management URL 
httpi:, 1 . 1 njn.cloudbees.coi 
manage/devefcrpm e nt : a ndy- pelietla 1 chattum 

URL 

htl p : .''.''c- hat ru rn . a ndy-petf efla . c toudbees . net 



Database Chatrum-16 

Management URL 

htt ps : /.' run . t loudbees . conV ai anxJy-petfefla*Wb-managB:Chatnjm-16 



Congratulations! 

Your Playf Framework 2 application. Chatrum, has been deployed to the account: 
andy-petrella. It is now ready to use. 



Close Dialog 



Open Application 



Amazing, huh? We can now check off, in two clicks or so, a source repository (Git), a 
Continuous Integration server (Jenkins), a web administration interface (CloudBees' 
interface), and even a database (MySQL) ! 
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We're about to see how to use them all, but first we must open the application by 
clicking on the Open Application button. This will lead us to our account interface 
from which we can access all of our services for all of our applications: 



Welcome to CloudBees - Click a service to get started! 



Community Links 

© HI* 



Quick Reference 



Setting Started 



© iCKwdPiw rjrjtr 



CkxjrfBim fof ErJvao 



Recant Blog Entries 

• Mnm rmMn and *TTm Mmn Way* 

> Htm BuWNw inlg OshKib 

> MdhMI VpMMtp cti Onitw T«j 



Ptv .-vt] Hw 



As we can see in the preceding screenshot, we can administer everything from here. 

As mentioned before, we'll only focus on the first three icons — Repositories, Jenkins 
Builds, and Applications. The first will show us how to deal with the Git repositories 
we have at CloudBees, in this case there is only the chatrum repository (see the 
following screenshot): 



FWQB * CftBHTJlTl 



andypctrclli/thslniin GIT repository 

Population of [his repository from Che archetype o^t://gioV*.conVC10LtdBe«- 
conmunlty/tf iy£-£llckitart,{iit lucceedea. 



git cler.e Mki/ffit4fi«,cl*P*f**t«1 

•Cho 'Frpo-iinry ch4St«»' > KM SHE 
rjll «W WWW 

cjic cmii -u *fitit1*l cbaciin' 
fit pumh origin Mtti: 



^ Account Aceeu -etwigaj 
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The interface includes a lot of information about the Git repository, for example, its 
URL, its visibility, and so on. The bottom-left corner also explains how to use the Git 
repository in the cases where we already have some code to push (which might be 
available from another Git repository) or if it's a brand-new application (when we're 
starting from scratch). The cases are grouped within accordion panels. 



Note that the created repository already contains an empty Play! 
Framework 2 application, which has been deployed at the same 
time. So to be able to push an existing project to this repo, we must 
ask Git to force the push. 



After having pushed our chat rum application to this repository, it would now be 
worthwhile seeing how to run Jenkins on it. 



[ 



Don't forget to upload your SSH public key so that you'll be 
able to use the services easily from your own machine. 



] 



For that, we can click on Builds in our top navigation bar; it's a shortcut to our 
Jenkins' administration interface: 
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It appears that it's just a classic Jenkins console, but embedded within the CloudBees 
interface. And what's already out there? Our chatrum application 
of course! 

Indeed, at this stage, a Jenkins' job has already been created for our application. 
However, its sole task for now is to check the code repository for changes and 
build the application without testing it by default. 

That's great, but since the tests aren't being run, we're breaking the Continuous 
Delivery process. We must now ask this job to run the tests, which automatically 
implies that the application won't be deployed if at least one test has failed. 
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[ 



Yes, the application is deployed as well when built. We're 
X allowed to disable this behavior or to tune it, but we won't 
cover the deployment phase in CloudBees here. 



] 



This can be achieved by going to the configure page of the chatrum job, as follows: 



All + 


S W 


Name 1 Last Success 


• m 


chatrum 1 hr 18 min f#81 


j&* Changes 
^ Workspace 
^) Build Now 

Delete Project 




[con: 5 ML 






Configure ^ 






Groups 
^ Roles 






J Forge Hook Log 





In this page, we'll have to update the Build | Execute Shell command, which 
CloudBees has configured for us. 

We'll add the following two things: 

• A test goal, asking Jenkins to run our tests 

• A configuration for a display environment, which is helpful for tests 
using Selenium 



Code Once, Deploy Everywhere 



This is done by updating the default command line in the text area. In the following 
screenshot, we can see which command has been set up by CloudBees for us: 

Build 

Execute shell £ 

Command 3ava _ Xm5512M - X ]nKl536M -XesIK -XX : +£MSCla i SETJnlDa 1 c£rigEnat i led XX V..r.: eh * . .• • IM -jar / opt /sb t/sbt-launcb-0 . 1 1 ■ 3-2 ,j ar - 
Dabt.loc.noforjTLat^true clean compile dist 



And the next screenshot shows the resulting command line we must use: 



auiid 

Execute shell 



Xvfb 3 99 i 

ja\ra -Xms512M -Xmxlo^CM -XsslM -XX : +CMSCla55TJnloadingEnabled XXsHaxPern! ' A* -jac ; Dp t/ sh t; sb t-launch-0 . 11 . 3-2 . j ar: - 

Dsbt. log. nofocmat^true clEan tent dist 



What was done is that the compile goal was changed to test, and a display 
environment variable for a virtual display server was added. 

So far, so good, we're going to make a little change in our code, push it to CloudBees, 
and finally check what's going on. The change we will make is asking Selenium to 
use Firefox rather than its in-memory web browser; since it's a very simple change 
in the code, it looks fine for this example. To do that, simply navigate to workflow/ 
RegisterSpec . scala and replace HTMLUNIT with FIREFOX. 

Now we can commit the change and push it back to the CloudBees code repository, 
and then get back to the Jenkins console. We'll see that a new build has been 
launched, thanks to the Git hooks and the configuration, which CloudBees has 
made for us. 
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So, we just have to wait for this build to finish (and succeed obviously) to enter the 
build's result by clicking on its item in the bottom-left panel. A Jenkins job result 
page has a menu item to view the console output (on the left-hand side navigation 
bar); if we click on it, here is what we'll see: 



andy-petrella 



[info] 
[info] 
[info] 
[info] 
[info] 
[info] 
[info] 



+ that succeeds 



rfill redirect to the dashboard paa 



Total for specification LoginSpec 
Finished in 12 seconds, 13 ms 
5 examples, failure, error 



r [info] 
. [succe: 



Passed] : 
s] Total 



Total 13, 
:ime: 338 



Failed 0, Errors 
r completed Dec 3 



, Passed 13, Skipped 
2012 7:34:33 AM 



[info] 
[info] 



Packaging / scratch/ jenkins/ workspace/ chat rum/ target/ scala-2 , 9 , 1 /play- jbook_2 , 9,1-1, 0-SNAPSHOT, jar 
Cone packaging. 



Your application is ready in / scratch/ jenkins/ workspace/ cha t rum/ dist /play- jbook-1 , Q-SNAJPSHOT. zip 
[success] Total time: 10 s, completed Dec 3, 2012 7:34:43 AM 

Process leaked file descriptors. See h t tp : _^ ; . ' . Mild for 

more information 

Deploying as (jenkinsj 
Deploying to andy-petrella account 
Deploying dist/*, zip -> chat rum 



cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
clou db e e s - d ep 1 o y e r 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cloudbees-deployer 
cl OMdhees-depl oyer 



cloudbees-deployer 
cloudbees-deployer 
uluuJLiyyt-JyjJluyyi 



MB 

1 ME 



7 ME 
3 MB 

10 ME 

11 MB 

13 MB 

14 MB 

15 MB 

17 MB 

18 MB 

20 MB 

21 ME 

23 MB 

24 MB 

26 MB 

27 MB 



Deployed to application id andy-petrella/ chatrum 

Can he accessed =i , ; . . ■ . . :,■ • 

tyjjluyyj aiLlfauL Juyt luL Lawu a fiuyyiyiiuL lyuuu 



Hurray! All tests passed! So we're now ready to code in a peaceful way, even with 
several devs on the same code base or in different time zones. At least, we know that 
the future commits won't break the application for the currently tested specifications. 

As you can see, a second box has been drawn around another message, which 
notifies the user that the application has been deployed as well. However, the 
deployment part will be covered in the next section using Heroku. 
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Deployment (Heroku) 

Part of the Continuous Delivery process, the deployment phase is one of the most 
critical. An application when deployed, is released into the wild where innocent 
monsters (users) are massively mistreating it (using it). 

The deployed version is the one that will be used, it will show end-users the new 
features, bug fixes, and so on (or the problems, if any). It has to be resistant to peaks 
of use. So there are several needs that we might find very helpful at deploy time. 
Examples of those needs are the ability to redeploy quickly and easily when hot fixes 
have been made, or to scale our application horizontally when running on the cloud. 

Nowadays, a great solution to those problems is the Heroku provider 
(cloud hosting) that comes with a PaaS, which is completely independent 
of the underlying infrastructure. And managing a running application is 
very easy, thanks to their amazing Toolbelt tool. 

Okay, calm down! Let's rewind a bit and briefly introduce what Heroku is. 

Heroku offers a hosting platform for cloud applications. For this it supports a 
plethora of different languages from Ruby to Scala, through to Java or Python. 
Their philosophy is their key value. As mentioned earlier, their platform is 
completely abstracting the machines that were started under the covers for our 
application. All we have to deal with is what they term as dyno. What we must 
understand about a dyno is that it's like an isolated unit of work dedicated to our 
application, which is able to receive requests or run commands. In one word, it's like 
a small machine, we don't have to manage anything. 

A dyno is built in such a way that our application can run on it, receive requests, 
or even start batch processes. The coolest part is that we can add as many dynos 
as we like (to pay for). Moreover, Heroku deals with them in a completely 
fault-tolerant way. 

The free service provides only one dyno for free. J 

So those requests and processes are dispatched, balanced, and recovered out of the 
box— these problems are no longer ours! Isn't that beautiful? 
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Furthermore, their ever-increasing popularity has been reflected in the number 
of tiers' services that have been integrated with their platform as add-ons. 
This fact results in a very wide ecosystem, including ElasticSearch, Cache, 
and NoSQL databases. 

Great! After this quick introduction to Heroku, let's see how to use it. This leads us 
to use their Toolbelt tool — a command-line tool enabling any application running on 
Heroku to be remotely scaled, monitored, restarted, and so on. The best option, now, 
would probably be to install it and deploy our application on Heroku. Its installation 
is pretty simple and very well explained at https : //toolbelt . herokuapp . com/. 

jk« Obviously, we need to have an account on Heroku to be allowed 
( ) to deploy our application on their platform. For this, we just have 
V) to follow the instructions on the login page. 

With our account created and the CLI (toolbelt) installed, we must now get back to 
our application, using the console. From here, the deployment is rather simple. First 
of all, we have to create our application on Heroku, which will add it to our account's 
administration console. This can be done as follows: 



nooQtsab@noootsab-xps-ubuntu:~/src/book/play- jbook$ heroku create 
Creating arcane-castle-4928. . . done, stack Is cedar 
BUILDPACK_URL=https://github.coFi/ndeverge/heroku-bulldpack-scala.git 
http: //arcane- castle- 4928. herokuapp. con/ | git@heroku. con: arcane- castle- 4928. gtt 
noootsab@noootsab-xps-ubuntii:~/src/book/play- jbookS git push heroku master 



Yeah, really, two commands and we're done! 

Actually, the first command will create an application on Heroku for our chatrum 
app with a generated name (arcane-castle-4028), the second will push our code to 
the Git repository that Heroku has created along with the application. 

If you don't want Heroku to generate a name for your application (that you still 
can change in your administration interface on the website), you can update the 
command as follows: heroku create <your-chosen-name>. 

This Git repository will be used by the Continuous Deployment feature of Heroku. 
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When new commits are incoming (pushed), they will ask Heroku to try and redeploy 
our application. So, let's try it directly by pushing our code into this repository and 
see the next screenshot for an excerpt of the output. We can see that it has detected a 
Play! Framework 2 application. Since it knows how to deploy such an application, it 
did this deployment for us, directly! 



noootsab@noootsab-xps-uburitu : - / >ok$ git push heroku master 

Counting objects: 109, done. 
Delta compression using up to 4 threads. 
Compressing objects: 199% (89/89), done. 
Writing objects: 199% (199/100), 77.22 KlB f done. 
Total 190 (delta 8), reused (delta 9) 

> Heroku receiving push 

> Fetching custom git bulldpack... done 

> Play 2.9 - Java app detected 

> Installing OpenJDK 1.6... done 

> Building app with sbt 

* Runnlnq: sbt clean compile staqe 

[Info] Packaging /tmp/bulld_17vlkpurkbpek/target/scala-2.9.1/play- jbook 2. 9.1-1. 9-SNAPSHOT. jar . . . 

[Info] Done packaging. 

[Info] 

[Info] Your application Is ready to be run In place: target/start 
[Info] 

[success] Total time: 54 s, completed Dec 3, 2912 9:99:94 PM 

> Dropping Ivy cache from the slug 

> Discovering process types 

Procflle declares types -> (none) 

Default types for Play 2.9 - Java -> web 

> Compiled slug size: 37. 9MB 

> Launching..* done, v7 

http://arcane-castle-4028.herokuapp.com deployed to Heroku 

To glt@heroku.com: arcane -castle -4028. git 

* [new branch] master -> master 



You might wonder how to open it. Try executing heroku open in your console. 
Great! It opens our application in our default browser. 

The problem is that we're not quite done, because of what is displayed on the screen 
(an error message): 



Ct ft O arcane castle-4G28.herokuapp.com 



Application Error 



An error occurred in the application and your page could not he served. Please try again in a few moments. 
If you are the application owner, check your logs for details. 




[242] 
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Ouch! What's that? Since our tests are running, everything should be okay 
on production. 

Our reflexes should have been shaken in a way that our eyes should have already 
been looking for the logs. Right, that's easy, use heroku logs! 



7017- 17 -01! 71 :31 ; 46+00:00 app[*eb.l 

2912- 12-03T21: 31: 46+00:00 ipp[w?b.l 
rtct on update restrict; 

2812 12 03721:31:46*09:00 jpp[wcb. 1 

7017- 17-03171 : ii :46+eo:ae appfweb.i 

2012 12- 03T21: 31:40*09:00 app[w«b.l 

7817- 17-01171 : 11 : 46+09:00 appfweb.i 

2012-12-03121:31:40*00:00 jpp[mrb. 1 

?017-1?-93T?1:31 : 46+00:00 appfweb. 1 

2912 12 61121:31:46. 99:00 app[vcb.l 

7917- 17-03T71 : 31 : 46*90:00 appfweh. 1 

2912 12-61121:31:46*69:60 app[vcb.l 

7012-12-03T71 : 31 : 46*69:00 appfweb.i 
trlct on updale restrict; 

7917- 17-03T71 : 11 :46+00:00 appfweb. 1 

2912 12 01T21: 31:46*69:66 jpp[wcb. 1 

7017- 17-03171 :31 : 46+09:00 appfweb. 1 

2912 12 6U21: 31:46*69:66 app[web.l 

7917-17-01T7I :3l : 46+09:00 appfweb. l 

Z91Z ■ 1Z-03TZI: 31:46*00:00 appfweb. 1 

2912-12.03T21: 31:46+09:00 appfwtb. 1 

Z91Z 12 '03121; 31: 40*09:09 app[web. 1 

7Q17- 17-03T71 : 31 : 46 + 00:09 appfweb. 1 
scala. collection. LlnearSeqCpltnli 

7017-1?. S3T7t : 11 : 49.00:00 heroku[wi> 



[..- .] play - Run with - Dappl ytyolu t ion*, .defaul t = : rur- if you want to run them automatically (be careful) 
■ Iter table Lnatjc add Constraint fk_tm*fl*_us*r_2 Foralgn key ( u r _ end t, L ) references user (en*tl) on dele 

at Scala, col lection. tmnu table. List. foreach(Llst r 5Cdl*:4S) 
At play . care, Stat IcApplic at Ion. xintt>(Appl Icat Ion Provider . scala; St} 
at seal j .Option r map (Opt Ion. tea Id: 13 J J 
at play .apt .Play$£anonfun£start$l .apply (Play, scala :6B) 
at play .apt .Play$. start (Play, scala : 49) 

at seal a . collection .Linear SeqOptinljed^clasn, foreach{LlnearSeqQptlml zed. scala : 59) 
at scald . collection . limi tabic. List . r orcach{Llst . sea la: 45) 
at play .core. server .Net tyServer$. create^erver (Net tyServer . scala: 137) 
a I play .core. server .Net tyServerSSanonfunSmalnS 5 . apply(Netty5crver .scala: 153) 
alter table Item add constraint fk_tten r _chat_3 foreign key (CHftT_ID) references chat (tnternal_Ld) on del 

Oops, cannot start the server. 

at play.apt .rfb.cvolut lens. EvolutlonsPlijgln5S<]ncnrun'5Qn5ldr til .apply (Evolutions . scala:422) 
at play .apt .Play$$ananfun$start$l .apply (Play. scala :69) 
at play .core . server .HettyScrver . ma In (Welly Serve r , scala} 

at play .apt .db. evolutions. Evolu I lonsPlug In .on5 tar Involutions . scala; 410) 
at play .core .server .Net ty£«rwr$.fialn(HettyServer . scalar 152) 
at play .core . server .Net LyScr* eriSanonrunS-nalnSS . applytNcttyServcr .scala: ltz) 
at 

cd$ctass . for cacM Lin earScqQpttmlzcd. scala rss) 
Process exited with status 7SS 



Amazing, our logs have been fetched from the server and shown in our console! 
And, what they are indicating is that we must apply evolutions to our database. 

That's right, our application is using evolutions to manage the version of our 
database schema and this same evolutions plugin has detected that our (in- 
memory) database is not up-to-date. But since the application is currently running 
in production mode, we cannot have the common web page we had in dev mode, 
which asked us to apply the updates manually. 

To overcome this problem, we'll take a shortcut and ask Heroku to always 
update the database schema when needed (on restart/ redeploy). But we'll 
also take the opportunity to use the database that Heroku has provided by 
default— a PostgreSQL database. 

To use this database and to configure an automatic application of evolutions, that is, 
to configure how Heroku should behave, we can use a specific file that Heroku will 
use on deployment— a Procfile file. 

This file is meant to configure the processes that Heroku must start on our dynos. In 
this case, we need to update the way the Play! 2 application's process (called as web 
process) is created. 
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The Procf ile file must be created in the root of our application and will look like 
the following: 



Procfile 



veb: target/start -Dhttp . pcrt=${PORT} ${JAVA OPTS} -DapplyEvoluticns . defaults rue 
Ddb , default . dnver=org .postgresql . Driver -Ddb , default . urT. = ${ DATABASE URL} 



In this file, we can see that we created a web process using the target/start script. 
This process is running a JVM to which we've passed several options to be used 
by the application, for instance, the port to listen on, or the default Java options set 
by Heroku. Note that we've just reused some environment variables provided by 
Heroku, and the same goes for our database URL. 

But what has been done in this Procfile file to resolve the database status problem 
is the addition of the applyEvolutions . def ault=true option. This option tells the 
application that we want evolutions (l . sql) on the default database to be applied at 
start time, where this default database has been reconfigured by two other variables 
targeting the PostgreSQL database that Heroku is providing. 

To check this solution, we can do the following: 

1. Commit and push this new file to the Heroku Git repository. 

2. In the console, use heroku restart. 

3. When restarted, check that the web process is started using heroku ps. 

4. Open the application using heroku open. 

Your default browser will be opened at the application's URL and will show you the 
login page. Hurray! 

Now that the application is running, we would like to know if the current 
deployment is sufficient for the load, and we would especially like to monitor some 
metrics. Indeed, at runtime there are plenty of variables that might slow down our 
application, or even blow it up. That's where monitoring tools enter the game, and 
that's the topic of the next section. 
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Monitoring (Typesafe Console) 

In the cloud world (which we've entered recently), most of the new applications 
are running in virtualized environments that are sold as services themselves 
(I A AS, PA AS). 

This implies that a lot of responsibilities (infrastructure, network, OS, filesystem, and 
so on) are now out of our hands, which is good. But when we need to understand 
why our application has crashed or why it is particularly slow, we should be able 
to get our hands back on some of the responsibilities. For instance, our application 
might be slower at some point because the host network is overloaded or because the 
file system is being archived and is reducing the IO's performance. 

Those facts have increased the need for monitoring, and this need has been tackled 
by great teams, building great products; New Relic (http : //newrelic . com/) is one 
of them and probably the most famous one as well. 

Actually, the Typesafe team is part of those smart teams, and so it has recently created 
a brand-new product called the Typesafe Console. We'll take the opportunity to 
introduce this product in this section, but first of all, let me warn you of some things. 
This is a paid product; at the time of writing, however, it has been announced that it 
will soon be free for developers. 

Furthermore, this console is not yet ready to monitor a whole Play! Framework 2 
application. Indeed, its first goal is to monitor the Akka systems; nevertheless, this 
feature should come in the future. 

So far, so good, but what's that console? 

The Typesafe Console is a web application built upon the Typesafe stack 2, and thus 
it uses Scala, Akka 2, and Play! Framework 2. But it also uses MongoDB to store 
information about the metrics gathered from the running/ monitored instances. 
As this section is a short introduction to this product, we won't dive into too many 
details, but we'll have a quick overview of its features. 

The Typesafe Console is meant to monitor and trace the deployed event-based 
systems using Akka. By capturing these events, it is able to compute metrics on 
them and to present them in a neat, clean, and beautiful web interface. And so, no 
matter whether our application is deployed on several nodes or using the remote 
capabilities of Akka, the console remains the single monitoring point. 
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See the next screenshot to know what the console looks like and what it can display. 
If you want to see it in real life, you can, of course, download it and try it, or you can 
also go to http : / /console-demo . typesaf e . com/: 



n:iwd#l 



jp TY(>&63f$ Documentation v Demo 

Search (or "help') 
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... 



In the preceding screenshot, we see that we can monitor several nodes (two in this 
case) and the system itself (with some filters enabled on the top right). 

From here, a lot of views are available because almost everything is clickable, which 
results in a different view (scoped). For instance, one could see the status of the 
dispatcher of the second node: 
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Or even see the workload of a particular actor (a piece of work): 




Having that for Play! Framework 2's internals (requests, accesses, and so on) 
will be awesome! 

Summary 

In this chapter we mostly talked about the tools to reach a Continuous Delivery 
process for our application management, using some tools running in the cloud. 
It was mainly divided into three parts; we started with Jenkins, the Continuous 
Integration tool, available on CloudBees. This phase checks that the application has 
the expected quality (statisfies all tests) independently of the host machine. 

Then we saw how to use the Heroku platform to deploy a Play! Framework 2 
application and took the opportunity to switch from an in-memory database to a 
production database — the PostgreSQL database provided by Heroku. 

And finally, we introduced the Typesafe Console that will be the next killer tool for 
any Play! Framework 2 application, giving us a view of our application's health. 

This chapter also ends the book for the pragmatic parts of Play! Framework 2. 
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The following chapters— appendices— will talk about where to go from here, for 
even more advanced use cases. Those use cases would have been far too much for 
the scope of this book, and would require a dedicated book in itself. 

Before getting to these points, we'll also have an overview of the core concept of the 
Play! Framework 2 — the why and how. 




Introducing Play! 
Framework 2 

In this appendix, we'll spend some time speaking about Play! Framework 2 itself 
rather than exposing what it can do, which, by the way, was the role of the book's 
main content. 

The following topics will be covered in this appendix: 

• What is, in fact, Play! Framework 2, and what are the use cases that will fit 
perfectly with this framework 

• A glance on the core ideas 

• Why the need for such a framework was so strong that it already has a 
second version of it 

• Why the second version is better than the first, and what the differences are 

• A quick overview of the goodies given to developers 

Why do we need Play! Framework? 

The first thing to understand and to keep in mind while using Play! Framework 2 is 
that it is a pure and full-stack web framework on the JVM. Creating web applications 
using cutting-edge technologies is its first purpose, and it is the best at it. It is the 
best as it gives developers a great and positive experience while creating web 
applications. This experience comes with the fresh and neat vision that Play! 
Framework has on how web development should be done. 

The most appreciated feature from the developer's perspective is the short overhead 
between the code session and the result in a web page, which is near to zero, thanks to 
the hot reloading of any source files and the compilation errors shown in the browser. 
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Framework for the Web 

This new framework has been built by taking some references from the Web world 
and its success stories. Some of them are Ruby on Rails or Django in Python. They 
bring to the JVM some facilities that aim at simplification of the work; for instance, 
eliminating the boilerplates necessary to set up a development environment around 
the framework. 

Indeed, its full-stack approach means everything is prepared for us — all we need 
is already there. Not that we're forced to use everything or we cannot swap a 
library for another, but it's just that without specific actions and efforts by the web 
developer, we don't have to do anything else but simply install the framework and 
start working. And it's on the JVM — that means we have all the tools from one of the 
biggest communities out there to help us in our daily work. 

In short, Play! Framework 2 is the fastest way to create amazing applications that 
make usage of all new features brought by the Web. Thus, it's also the best way to 
show these new features! 

Not JEE-based, but JVM 

We have to mention that Play! 1 didn't follow the JEE specifications and abstractions, 
and there are no reasons to have Play! 2 follow them either. Where most of the 
abstractions in J2EE, at some point, eased the developer's work, nowadays they are 
constraining him/her with what was foreseen years ago. But the Web is evolving so 
fast, with needs that are completely different than were half a decade ago or so. 

For instance, every year HTML5 has better support, and this specification along 
with the Web is including many new features that help in building applications very 
easily and in an integrated way. Examples are WebSockets, caching control, security 
headers or metadata, and so on. While these features have to be enabled in JEE, they 
haven't been hidden in Play! 2. 

Learning from the past, where the first version supported the Scala language 
through a plugin, this new version has been built upon Scala from the beginning. 
Because Scala and the functional paradigm fit very well with highly -concurrent 
applications, like a web framework should be, they both helped a lot for Play! 2 
to be a highly-reactive web framework. 
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However, even if Scala is gaining in reputation, the Java community with its tooling 
and its amazing set of libraries, and also its "quasi-omnipresence" still has a place of 
choice; that's why a Java-specific and adapted API is there for us. This might enable 
a developer to mostly ignore the Scala language itself, apart from the templating and 
build system. 

Underlying ideas and concepts 

The Play! Framework internals are based on very light and trivial concepts. One 
of them is that the application should be separated from the Web by a single thin 
layer— its API. 

Reactive 

This framework helps in solving a fundamental problem in web-based 
applications: the reactivity of a web server within a distributed environment. 
In the following sections, we'll see which points are critical to building a 
sustainable and relevant solution. 

NIO server 

A Play! 2 application is completely stateless, that is, no state can be stored on the server 
to cover multi-request workflows. This fact will oblige applications to use different 
patterns or to use specific tools to deal with a state— such as a caching system. 

For responsiveness, they took the opportunity to distribute a dedicated server as part 
of the stack, which is the non-blocking JBoss Netty server. This server is different 
from others because of its behavior. Indeed, rather than dealing with threads for 
every single request that is coming, it uses an event-based architecture where events 
are created when a request is effectively asking something or sending something 
to the server. That will help the server not to wait for a request to finish before 
switching to another, or in other words, to block a thread until the request has 
something to do. 

This kind of behavior is contrary to the "one user, one thread" concept, which leads 
the server to only serve as many users as the number of threads it can deal with, no 
matter what they are doing. 
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Asynchronous 

But the responsiveness is not yet accomplished if we only tackle it in the core, 
because a developer could block a thread on an external working process, such 
as a web service call. 

In order to avoid developers doing that, Play! Framework 2 can declare a process to 
be asynchronous and leaves the server to choose when to process it or when to come 
back on it. For example, if a process is running on an external machine, but the local 
thread is simply waiting for an answer, this thread can be retrieved for other tasks 
until the remote call has returned. 

Iteratee 

However, that's still not enough, thanks to the Scala language and its ability to 
use functions as objects. Play! 2 uses Iteratee to add some responsiveness to handle 
request bodies themselves. So the body to be processed as an XML or a JSON is no 
more blocking the server because an Iteratee can pause its work until the server, 
which is responsive in itself, has some data. 

Furthermore, it's composable, which adds a new value to the framework, because it 
prevents a body (that could be large) to be processed several times for transformation 
purposes (bytes to string to JSON, for instance). 

Wrap up 

Using Play! Framework 2 and by following their conventions, any application is 
ready for the Web, or more than that, it is ready for the cloud. 

What's new? 

The following sections will be dedicated to what comes with this new version of 
Play! that wasn't available in the first version. 

Scala 

As said earlier, this version has been built using Scala as the core language, whereas 
Play! 1 uses the Java language and provides support for Scala. 
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Simple Build Tool 

But that's not all! One of the biggest changes of Play! 2 is its console. Indeed, Play! 
l's console was a custom one, using Python to reduce the memory footprint and the 
need to start a JVM all the time. This has been revoked in Play! 2 because of Simple 
Build Tool (SBT). This build tool has the disadvantage of starting a JVM but, you'll 
start it only once! This is because the SBT console is a "real" console as it provides 
commands, tasks, and so on. 

Furthermore, SBT is easily extensible and that's exactly what has been done for Play! 
to enable or customize specific actions for it (such as run). 

Templates 

In this new version, where Scala was chosen as the core language, the Play! 
Framework 2 team has also chosen Scala for server-side rendering. This means that 
they have built a brand new templating system that uses Scala rather than Groovy in 
the first version. 

However, they didn't use Scala as just an empty language to generate HTML 
(for instance); rather, they integrated the generated page (or data) with Scala. 
And how did they accomplish that? By producing a regular Scala file that will 
be compiled. Hence, writing a template is type safe; they can be composed easily 
and have a steep learning curve. 

Assets 

A web application will always come with assets that are meant to be served 
as is by the server. However, those assets will be optimized by Play! for us, by 
precompiling them or by using an HTTP mechanism to reduce the server's work 
to serve them. One example is to use the ETag header to avoid resending the same 
thing again and again. 

That was for performance, but Play! has been created by web developers, and only 
they know what other problems they had with assets such as JavaScript and CSS. 
That's why a new feature that comes for free with Play! 2 is the ability to write 
compiled assets such as a CoffeeScript file for JavaScript or LESS CSS for CSS, 
without any configuration or additional tasks when starting to work. 

The integration of these languages has been done deeply, so their compilation 
errors are shown to the developers like it is for a classical "server" code, which 
is on the browser! 
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Amazing goodies 



This section is reserved for stuff that you probably won't find out of the box in most 
other web frameworks except Play! 2. As this framework is pretty recent, it has 
directly embraced all the new stuff that is required for applications willing to stick 
with cutting-edge technologies, HTML5 being the first one. 



HTML5 has defined a bunch of new concepts that aim to ease the work of all 
developers if their web frameworks allow them or provide APIs to support them. And 
that's the case for Play! 2 because of its architecture, which is very simple and does 
not try to abstract too much, that is, Play! 2 doesn't try to hide the fact that we're using 
HTTP and HTML to deal with a browser or a service. This results in the fact that a 
developer is able to add the support to a new header without hacking Play! 2, or is able 
to support a new type of streaming protocol without breaking the others. 

The following are a few examples: 

• Server-sent events: Part of the HTML5 specification, this concept enables 

a server to push events to a connected client. This can be enabled in Play! 2 
using an open connection and can push data to it. 

• WebSocket: This is yet another part of the HTML5 specification, which 
enables a bi-directional connection between a client and the server. No need 
to implement it since Play! 2 is already implementing it, and in a reactive 
fashion. So we've just got to use the dedicated API for that. 

• Comet: This is not part of the HTML5 specification, but was the predecessor 
of SSE for those applications that needed a server push functionality. The 
same remark was said for WebSocket; everything has been done in the Play! 
2 API to enable a developer using Comet easily. No need for a brand new 
API like it was for the Servlet API. Indeed, a new Servlet API was created 
back in 2009; it was the third version in order to enable such features. 



HTML5 




The WebSocket Java API is still under discussion (the JSR 356), 
and that's another clue that Java is somehow breaking the early 
access to new web features. 
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External services 

HTML5 is not the only great support that Play! Framework 2 is providing us. There is 
also the support of web services. There is a part of the API that is completely dedicated 
to handle WS calls in a reactive fashion (using the Promise and Iteratee concepts). 

By respecting Play! 2's conventions, an application can make excessive usage of 
external services without suffering extra latency or bad response times for regular 
requests. This is possible thanks to the asynchronous feature of Play! 2. 

Form validation 

Another tool in Play! 2 is the validation of HTML forms on both sides: client and 
server. Indeed, you can rule the way data is provided to a server at runtime by 
adding constraints on them. Plenty of constraints are defined in the API but we 
can also create our own. 

More than this runtime validation, a validation can be done at compile time using 
the power of templates. Indeed, as a form is represented on the server side to match 
a specific type structure (hey, we're in Java or Scala!), and that the templates will take 
those forms as parameters to create HTML ones, the compiler will be able to find 
problems with types. 

We can easily create a workflow that deals with validated deep structures, without 
boilerplates and also without any fear, thanks to the type safety brought both in the 
templates and in the action. 

Hot reloading 

One of the biggest advantages of this framework is hot reloading! For those used to 
Java web frameworks, you know how hard and long the path is to go from a line of 
code to a manual test in a browser. 

Most of the frameworks deal with J2EE interfaces that require a specific runtime 
environment, such as a servlet container or even an application container. These 
servers need packaging of the code to run it, so developers need to create this 
package before being able to test it. Or, it can bind an IDE to a running instance 
to hot swap the code; however, it won't work for changes in interfaces, signatures, 
and so on. 

Play! 2 being out of that world and without those constraints, plus the fact that it 
has the full control on the environment (as it's a full-stack framework), they took the 
opportunity to resolve all points by enabling hot swapping of the code, using hot 
reload of the classpath. 
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OK, that's not a new feature for Play! 1 developers; however, for others and for Scala 
ones, it is! 

Only two tools - IDE and browser 

This section is quite similar to the previous one. We already know that Play! 
Framework 2 is a full stack and is completely integrated for web development. 
In addition, it has also solved another frequent problem when creating a web 
application. This problem is the time spent on looking for errors. Are they in the 
server log, in the application one, or in the console? Or, maybe, nowhere because it 
misses a configuration file? 

The answer to all of these questions is that you don't have to ask them. Everything 
will be shown in the browser when using it. That's it! You won't have to wonder 
where are the errors, because they're shining with red lights in front of you. 

Moreover, error types span from the server-side code— whatever it is, Java or Scala — 
to the client code, for both CoffeeScript and LESS CSS files. 

And that's why a developer only needs two tools during development: an IDE to 
write the code (or an editor with syntax highlighting features) and his browser. 
Actually, there is also the console, but, in development, you'll probably never 
go to it after you've launched the application (run). 

Summary 

In this appendix, we've seen a bit further more on what makes Play! Framework 2 so 
great. We took the opportunity to have a look at the core ideas and also compared 
them to the mainstream ones. We also had an overview on the new features brought 
by this second version, and what has been changed from the first one. 

All this leads us to discuss and to list which specific functionalities are worth 
considering when envisioning Play! 2 in a new project, for instance. 




Moving Forward 

In this appendix, we'll try to gather as much extra information as possible for those 
willing to go further from this point. 

Even though we covered a lot of ground in this book, the Play! Framework 2 hasn't 
been covered entirely; there are yet some places to be discovered that wouldn't fit in 
this book— most of them are for advanced users, and some more specific to Scala. 

This appendix will relate information about the following topics: 

• Play's features and internals that weren't covered 

• Features that were covered, but roughly or quickly introduced 

• Advanced features to ignite interest 

• Play's ecosystem 

• Play's communities — interesting blogs and groups 

More features 

Even though you have reached this point after reading the entire book and hacking 
with all the features introduced, Play! Framework 2 still has some areas where 
goodies can be learned. 

Plugin 

The first thing worth mentioning is its internal architecture, which is completely 
modular. This allows Play 2 to provide developers with a range of end-points to 
integrate an application perfectly with the framework; for instance, the application 
life cycle, or its configuration. 
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These modules are called plugins (as always) and a specific API is available for 
creating our own. This API not only enables a developer to hook on the application 
itself, but also helps define global components that can be used along with the whole 
application. Mostly, they are used for integrating third-party libraries. 



Global 

Another API is also available for those developers willing to interact with the 
application with a reduced set of needs; it is completely related to the application 
itself. This API is called global settings. For more information for the Java part on 
the 2.0.4 Version, go to http : //www.playf ramework . com/ documentation/ 2 .1.0/ 
JavaGlobal. 

So far, so good; those APIs are there to extend the application's capabilities 
in some way. However, there are even more features that a regular Play! 2 
application can offer. 



Session, cache, and M8n 

The two features that are really important for scalable applications are the session- 
like functionality of a request and the caching system API, available out of the box. 

The former enables a request to add or remove session information; this information 
is stored in the cookie until it expires and, on the other hand, short-lived data 
can also be consumed using flash scopes. For more information on the Scala part 
(2.0.4 Version), go to http : / /www.playf ramework. org/documentation/2 .0.4/ 
ScalaSessionFlash. 

For shared data, or for other use cases like that, we could use the cache API that gives 
the ability to store or fetch data to a centralized destination, which is independent of 
the user or the request. For more information, check this page (still Version 2.0.4) for 
Java: http : / /www. playf ramework . org/documentation/ 2 . . 4/ JavaCache. 

We didn't cover natural language and the classic internationalization (il8n) 
problem, but Play! Framework 2 already has everything covered for us. See 
http: / /www.playf ramework. org/documentation/2 . . 4/ScalaI18N. 



Frontend languages 

In this book we introduced CoffeeScript, but didn't spend enough time on it to 
grasp every single advantage of it. So, I'd recommend browsing this documentation: 

http : / / arcturo . github . com/ library/ cof f eescript/ index . html. 
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We didn't use LESS CSS here, but it's probably one of the best ways to achieve 
DRYness styling rules for a web application. This language aims to import all 
missing features to CSS, such as variables or functions. It's very easy to understand, 
and everything is documented at http : //lesscss . org/. 

Scala-specific 

In this section we'll try to, somehow, list what can be used in the Scala world. 

First, at the time of writing, Play! Framework 2 integrates ANORM as the default 
library for accessing relational databases. This library has been built internally with 
Play! and so is packaged with the distribution. Even if it lacks documentation at 
this stage, it has a good vision about how to access databases functionally using 
Scala. More information can be found at http : //www.playf ramework . org/ 
documentation/ 2.0. 4/ScalaAnorm. 

However, now that Play! Framework 2 is part of the Typesafe stack, it will be worth 
considering Slick too. Slick is the database access layer that is currently built at 
Typesafe and takes advantage of the new features of Scala in its 2.10 release. 

As the next release of Play will be based on this Scala version, Slick will also be 
available. Note that their visions are completely different; on the one side, Slick tries 
to enable an intuitive DSL integrated with the object model to deal with backend 
systems (relational and otherwise), while ANORM is not an object relation mapper, 
and so you're responsible for writing the SQL all by yourself (only relational). 

Furthermore, the Slick documentation is gaining some muscle and reaching a good 
level; it is available at http : //slick . typesafe . com/docs/. 

For very advanced workflows using the requests' bodies or resource handling in 
general, it's important to understand the concept of Iteratee. There are plenty of great 
blogs about it on the Web, some dedicated to Scala developers, others for those familiar 
with imperative coding. But the first page to look at is the internal documentation page 
at http : / /www.playf ramework . org/ documentation/ 2 . . 4/Iteratees. 

Although not really related to Scala (but Scalaers are more familiar with 
these concepts), Akka is another great toolkit to master in order to enhance an 
application with completely distributed computation or advanced concurrent 
workflows. Even if both the Scala and the Java APIs are amazing, knowing Scala 
(of a functional programming language) helps a lot understanding the core ideas 
such as Message Passing Style or Actors. Luckily, the Akka team is maintaining 
great documentation that closely follows any new features or changes. It is available 
at http : //doc . akka . io/docs/akka/2 .0.4/. Don't skip the general section! 
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Ecosystem 

The Play! Framework 2's ecosystem is evolving fast and well; a good metric is the 
ever-increasing number of questions related to it on Stack Overflow (nearly 2000). Its 
information page at http : / /stackoverf low. com/tags/playf ramework-2 . 0/inf o 
is a great place to search for advanced information. 

Another way to get help from the community is to use the Google group at 
http : // groups . google . com/group/play- framework, where hundreds of 
topics are discussed by developers, including Play! 2's committers. 

There are already a lot of applications built upon Play! Framework 2, so the number 
of use cases is increasing day by day. As a consequence of that, the number of plugins 
available for Play! 2 is also increasing very fast. At the time of writing, there are a lot 
of third-party tools, services, and libraries that can be easily integrated with it. 

Typesafe, by willing to have them gathered at a single place, has reserved a 
temporary place for them all at https : //github . com/playf ramework/Play20/ 
wiki /Modules. 

But there is another project that has started to ease the integration of new plugins; 
it enables developers to create their own plugins and publish them, with some 
constraints on the quality, using a rating system. This project is open source and is 
running well; it can be found at https : //github . com/play-modules/modules . 
playf ramework . org. 

As part of the ecosystem, we will find a lot of blogs that mostly contain information 
on Play! Framework 2's tricks and hints. A few of them are listed here: 

• http://mandubian.com/ 

• http : / /www . touilleur- express . f r (French) 

• http : / /www. obj ectif y . be/wordpress/ 

• http://ska-la.blogspot.be/ 

Obviously, you can also search for your local meet-up (or similar) group 
about Play! — there is always one, and that's probably the best way to be a 
part of the community. 




Materials 

In this book we've written a lot of code, incrementally building a full application 
called chat rum. 

A reference implementation exists for all chapters, both in Java and Scala, and they are 
available on GitHub at https : //github. com/andypetrella/play2 -book- chapters. 

To use this project, it would be best to fork it. For that, you will need a GitHub 
account; then, when logged in and on the project page, use the dedicated button 
named Fork on the upper-right-hand corner of the page. 

This forked project will allow you to adapt, fix, or do whatever you want with it 
(which I really recommend to you!). 

If you find some bugs and manage to fix them, I'll be grateful if you create a pull 
request on GitHub. This way I'll be able to integrate it and create the errata for 
the book. 

The content of this project is quite simple, since it contains one folder for every 
chapter. In each folder, there are two folders named play- j book and play-sbook. 
These folders are regular Play! 2 applications built on Java and Scala respectively. 

I hope you'll enjoy using them and also enjoy Play! Framework 2 in general, and 
you'll soon be creating amazing web applications. 
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Simple Build Tool. See SBT 
Slick 259 

sliding function 56 
spaces 149 
specs2 201 
splat parameter 167 
squareSeq function 205 
src attribute 135 
SSE 165 
ssynchronous 
String class 203 
string parameter 32 
style parameter 36 
Sublime Text 2 

using 21, 22 
symbol 90 

T 

TDD 199 
template 

about 33-36, 60 
components 60 
composing 63 
content, adding 61, 62 
creating 60 

data structures, passing 64-66 

modifying 36, 37 

structuring 61 
test command 204 
test-driven development. See TDD 
test folder 14 
test-only command 216 
tests 

about 200, 201 

atomic tests, running 204-206 
simple tests, working 202, 203 

TestServer class 220 

third party functionality 

problems 196-198 



Toolbelttool 240 
trait 49 

transient data 97 
Tuple2 class 76 
Twitter 

chatrum, integrating with 191-195 

interacting with 184-186 

Twitter API, using 187-190 
Twitter API 

using 187-190 
type inference 51 
Typesafe Console 230, 245-247 

u 

Ubuntu Linux 10 

V 

validate method 131 
variable 149 
View 69 

w 

web drivers 223 

web process 243 

web service 180 

Web Service API. See WS API 

WebSocket 

about 165 

adding 165-167 
WebSocket Java API 254 
with method 227 
workflows 

testing 220-227 

TestServer instance, creating 220 
WS API 180 
WS#url method 221 
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About Packt Publishing 



Packt, pronounced 'packed', published its first book "Mastering phpMyAdmin for Effective 
MySQL Management" in April 2004 and subsequently continued to specialize in publishing 
highly focused books on specific technologies and solutions. 

Our books and publications share the experiences of your fellow IT professionals in adapting 
and customizing today's systems, applications, and frameworks. Our solution based books 
give you the knowledge and power to customize the software and technologies you're using 
to get the job done. Packt books are more specific and less general than the IT books you have 
seen in the past. Our unique business model allows us to bring you more focused information, 
giving you more of what you need to know, and less of what you don't. 

Packt is a modern, yet unique publishing company, which focuses on producing quality, 
cutting-edge books for communities of developers, administrators, and newbies alike. For 
more information, please visit our website: www . packtpub . com. 



In 2010, Packt launched two new brands, Packt Open Source and Packt Enterprise, in order to 
continue its focus on specialization. This book is part of the Packt Open Source brand, home 
to books published on software built around Open Source licences, and offering information 
to anybody from advanced developers to budding web designers. The Open Source brand 
also runs Packt' s Open Source Royalty Scheme, by which Packt gives a royalty to each Open 
Source project about whose software a book is sold. 



We welcome all inquiries from people who are interested in authoring. Book proposals 
should be sent to author@packtpub . com. If your book idea is still at an early stage and you 
would like to discuss it first before writing a formal book proposal, contact us; one of our 
commissioning editors will get in touch with you. 

We're not just looking for published authors; if you have strong technical skills but no writing 
experience, our experienced editors can help you develop a writing career, or simply get some 
additional reward for your expertise. 



About Packt Open Source 



Writing for Packt 
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Cookbook 
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Alexander Reelsen 
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Play Framework Cookbook 

ISBN: 978-1-84951-552-8 Paperback: 292 pages 

Over 60 incredibly effective recipes to take you under 
the hood and leverage advanced concepts of the Play 
framework 

1. Make your application more modular, by 
introducing you to the world of modules 

2. Keep your application up and running in 
production mode, from setup to monitoring it 
appropriately 

3. Integrate Play applications into your CI 
environment 

4. Keep performance high by using caching 



Web Application Development 
with Yii and PHP 

ISBN: 978-1-84951-872-7 Paperback: 332 pages 

Learn the Yii application development framework 
by taking a step-by-step approach to building a 
Web-based project task tracking system from 
conception through production deployment 

1. A step-by-step guide to creating a modern Web 
application using PHP, MySQL, and Yii 

2. Build a real-world, user-based, database-driven 
project task management application using the 
Yii development framework 

3. Start with a general idea, and finish with 
deploying to production, learning everything 
about Yii in between, from "A"ctive record to 
"Z"ii component library 




Web Application Development 
with Yii and PHP 

Second Edition 



Lawn the Y ■■■ application development frame*ort by lakrfig a 
*1ee-by-Hep approach to buMinp a Web-fcased & oieci task 
tracking syilem from concoplwn th.-gurjh ptOducbon deploymerfl 



Please check www.packtpub.com for information on our titles 
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Yii 1.1 Application 
Development Cookbook 
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Alexander Makarov 



Yii 1.1 Application Development 
Cookbook 

ISBN: 978-1-84951-548-1 Paperback: 392 pages 

Over 80 recipes to help you master using the Yii PHP 
framework 

1. Learn to use Yii more efficiently through 
plentiful Yii recipes on diverse topics 

2. Make the most efficient use of your controller 
and views and re-use them 

3. Automate error tracking and understand the 
Yii log and stack trace 

4. Full of practically useful solutions and concepts 
that you can use in your application, with 
clearly explained code and all the necessary 
screenshots 




Yii Rapid Application 
Development 

Becom* a RAD hotshot with Y8, the world's most 
popular PHP framework 



Yii Rapid Application 
Development Hotshot 



ISBN: 978-1-84951-750-8 



Paperback: 340 pages 



Become a RAD hotshot with Yii, the world's most 
popular PHP framework 

1. A series of projects to help you learn Yii and 
Rapid Application Development 

2. Learn how to build and incorporate key web 
technologies 

3. Use as a cookbook to look up key concepts, or 
work on the projects from start to finish for a 
complete web application 



Please check www.packtpub.com for information on our titles 



